Pleaxy

Raise purchase orders, approve and pay invoices, and set up your workspace.

API reference

API keys

Keys that let your systems call the API without a person signed in.

More about this resource

Scoped machine-to-machine credentials, one per workspace membership (regionId + role). An Agent presents a key via the X-Api-Key header to call endpoints like SubmitInvoice (buyer keys) or FlipPurchaseOrderToInvoice (supplier keys) without a signed-in session.

Endpoints

Create API key

Creates an API key.

POST/v1/workspaces/{regionId}/api-keys

Body

  • labelstringRequired

    Human-readable label, e.g. "Billing agent - prod".

  • procurementRole"administrator" | "read-only" | "contracts-and-suppliers" | "relationships" | "requisitions" | "finance"

    Buyer keys only (ignored for a supplier key): what the key may do, by the same procurement roles people have. Defaults to read-only. For example, requisitions can create and edit purchase orders, and finance can work invoices. Whatever the role, a key never approves, rejects, records a payment (except through RecordPayments, with the payments:record scope), or changes approval flows, autonomy or automation rules.

  • scopesArray<"invoices:feed" | "payments:record">

    Only from an administrator, each for one side. invoices:feed (supplier keys) lets the key submit invoices through SubmitFeedInvoice; payments:record (buyer keys) lets it record payments through RecordPayments. Omit for a key without scopes.

Returns

201 Created with the object shown in the response.

More details

Mints a new API key scoped to the caller's own role in this workspace - a supplier can't mint a buyer-scoped key, and vice versa. The plaintext key is returned only in this response; only its HMAC digest is ever stored. Only an administrator can mint a key: on the Buyer side anyone else gets 403 ("Only an administrator of this workspace can manage its API keys."), and on the Supplier side 403 ("Only a supplier administrator can create API keys for this workspace."). A buyer key acts with the procurementRole it is minted with, read-only unless you choose another. A supplier administrator can add the invoices:feed scope, which lets the key call SubmitFeedInvoice on top of everything a supplier key already does; a buyer administrator can add the payments:record scope, which lets the key call RecordPayments and needs a procurementRole that can edit invoices (otherwise 400 API_KEY_SCOPE_ROLE_MISMATCH). A non-administrator asking for a scope gets 403 API_KEY_SCOPE_FORBIDDEN, and the other side's scope is 400 API_KEY_SCOPE_INVALID.

Requires a human Cognito session (Bearer token) - an existing API key can never mint or revoke another key. Only an administrator of the workspace can mint, list or revoke its keys.

Response fields

  • apiKeystring

    The plaintext credential, formatted "<keyId>.<secret>" - pass it verbatim as the X-Api-Key header. Shown only once; it cannot be retrieved again.

Errors

  • 403 Forbidden - The caller authenticated with an API key rather than a human Bearer token ("This action requires a logged-in user session, not an API key"), or, for Supplier callers, isn't a supplier administrator of this workspace ("Only a supplier administrator can create API keys for this workspace.").
  • 403 Forbidden - The caller's Bearer token or API key doesn't grant access to this workspace (regionId), or lacks the required role.
POST /v1/workspaces/{regionId}/api-keys
Request
curl -X POST "$PLEAXY_API_BASE_URL/v1/workspaces/reg_01k5x8p9j3q7vn2mhb4tzc6rde.supplier/api-keys" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "label": "Billing agent - prod" }'
Response · 201 Created
{
  "apiKey": "5b1c2e90-....-9a3f.9f2c7a1e8b6d4c0a2f1e3d5b7a9c8e6f",
  "keyId": "5b1c2e90-....-9a3f",
  "regionId": "reg_01k5x8p9j3q7vn2mhb4tzc6rde",
  "role": "supplier",
  "label": "Billing agent - prod",
  "createdAt": "2026-02-03T09:00:00.000Z",
  "revoked": false
}

List API keys

Lists the workspace's API keys.

GET/v1/workspaces/{regionId}/api-keys

Returns

200 OK with the object shown in the response.

More details

Lists API keys for the workspace. Never includes the plaintext secret or its hash. scopes is empty for a key minted without one.

Requires a human Cognito session (Bearer token).

Errors

  • 403 Forbidden - The caller authenticated with an API key rather than a human Bearer token. The response message is "This action requires a logged-in user session, not an API key".
  • 403 Forbidden - The caller's Bearer token or API key doesn't grant access to this workspace (regionId), or lacks the required role.
GET /v1/workspaces/{regionId}/api-keys
Request
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/api-keys" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Response · 200 OK
[
   {
      "keyId": "string",
      "regionId": "string",
      "role": "buyer" | "supplier",
      "scopes": [ "invoices:feed" ],
      "label": "string",
      "createdAt": "string",
      "revoked": boolean
   }
]

Revoke API key

Revokes an API key.

POST/v1/workspaces/{regionId}/api-keys/{keyId}/revoke

Parameters

  • keyIdstringRequired

    The API key identifier (not the plaintext secret).

Returns

201 Created with the object shown in the response.

More details

Revokes an API key immediately and permanently. A revoked key fails authentication on its next use.

Requires a human Cognito session (Bearer token).

Errors

  • 403 Forbidden - The caller authenticated with an API key rather than a human Bearer token. The response message is "This action requires a logged-in user session, not an API key".
  • 404 Not Found - No key with this id exists in the workspace.
  • 403 Forbidden - The caller's Bearer token or API key doesn't grant access to this workspace (regionId), or lacks the required role.
POST /v1/workspaces/{regionId}/api-keys/{keyId}/revoke
Request
curl -X POST "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/api-keys/{keyId}/revoke" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Response · 201 Created
(no content)
Talk to us