Error

A valid request URL is required to generate request examples

{
  "accessToken": "<jwt>",
  "user": {
    "id": "018f9a2b-7c3d-7e10-9a4b-2c1d5e6f7a8b",
    "abstractAccountAddress": "0x…"
  }
}

{
  "code": "INVALID_PARAMETER",
  "message": "scope is required"
}

{
  "code": "INVALID_TOKEN",
  "message": "Unknown agent API key"
}

{
  "code": "AGENT_KEYS_DISABLED",
  "message": "Agent keys are not enabled for this partner"
}

Agent APIs

Create a checkout session

Issues a short-lived access token (type=agent) for a merchant checkout. No refresh token. The bound key must include commerce.checkout.

Identify the agent with exactly one of the x-agent-api-key header or the body signedMessage.

The request scope names the merchant checkout target, not an agent scope. pivota.checkout is currently the only supported value. The JWT’s scope equals the requested value, and its aud is the merchant mapped to that target. The JWT includes the holder’s abstract account address.

AIR and Credential APIs reject this token because of the audience. The merchant must verify aud.

POST

auth

agent

checkout-session

Error

A valid request URL is required to generate request examples

{
  "accessToken": "<jwt>",
  "user": {
    "id": "018f9a2b-7c3d-7e10-9a4b-2c1d5e6f7a8b",
    "abstractAccountAddress": "0x…"
  }
}

{
  "code": "INVALID_PARAMETER",
  "message": "scope is required"
}

{
  "code": "INVALID_TOKEN",
  "message": "Unknown agent API key"
}

{
  "code": "AGENT_KEYS_DISABLED",
  "message": "Agent keys are not enabled for this partner"
}

Headers

x-agent-api-key

string

Opaque API key returned once at bind or rotate. Mutually exclusive with body signedMessage. Required for API-key-only agents.

Example:

"air_ag_…"

Body

application/json

scope

enum<string>

required

Merchant checkout target. pivota.checkout is currently the only supported value.

Available options:

pivota.checkout

Example:

"pivota.checkout"

signedMessage

object

Mutually exclusive with x-agent-api-key. The bound key must have a stored public key.

Show child attributes

Response

Checkout JWT issued

accessToken

string

required

JWT (type=agent) whose scope is the requested checkout target and whose aud is the mapped merchant. Not valid on the AIR or Credential API. The merchant must verify aud.

user

object

required

Show child attributes

REST API

Agent APIs

Web SDK

Releases

Create a checkout session

Headers

Body

Response