> ## Documentation Index > Fetch the complete documentation index at: https://docs.air3.com/llms.txt > Use this file to discover all available pages before exploring further. # 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`. ## OpenAPI ````yaml api-reference/agent-openapi.json POST /v2/auth/agent/checkout-session openapi: 3.0.3 info: title: AIR Agent APIs version: 1.1.0 description: > Partner-facing agent APIs for binding a holder's agent, minting a short-lived agent JWT, listing the holder's credentials, verifying them offchain, and minting a merchant checkout JWT. **Hosts:** AIR API (bind, keys, session, checkout) and Credential API (list, verify). The partner must have agent keys enabled. The AIR Kit partner access token is a **user-bound** holder session. **Typical flow** 1. Bind once (`POST /v2/auth/agent/keys/partner`). Save `agentApiKey` — it is returned only on bind and rotate. 2. Create a session per operation (`POST /v2/auth/agent/session`). The agent JWT lasts **15 minutes** and has no refresh token. 3. List (`GET /v2/credentials`) and/or verify (`POST /v2/credentials/verify-by-agent`) with `Authorization: Bearer`. 4. Optional: mint a checkout JWT (`POST /v2/auth/agent/checkout-session`) when the bound key includes `commerce.checkout`. Partner bind cannot include `wallet.sign`. `openid` is added automatically on bind. Partner scopes: `credentials.read`, `credentials.verify`, `commerce.checkout`. Mutating key routes (bind, rotate, revoke) require `x-partner-jwt`. Listing keys and updating a nickname use the AIR Kit session only. contact: name: Moca Network url: https://moca.network servers: - url: '{AIR_API}' description: AIR API (bind, keys, session, checkout) variables: AIR_API: description: Sandbox or Production default: https://air.api.sandbox.air3.com enum: - https://air.api.sandbox.air3.com - https://air.api.air3.com security: [] tags: - name: Agent keys description: Bind and manage partner-bound agent keys (AIR API). - name: Agent session description: Mint a short-lived agent JWT (AIR API). - name: Agent checkout description: Mint a merchant checkout JWT (AIR API). - name: Credentials description: List and verify the holder's credentials (Credential API). paths: /v2/auth/agent/checkout-session: servers: - url: '{AIR_API}' description: AIR API variables: AIR_API: description: Sandbox or Production default: https://air.api.sandbox.air3.com enum: - https://air.api.sandbox.air3.com - https://air.api.air3.com post: tags: - Agent checkout summary: Create a checkout session description: > 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`. operationId: createAgentCheckoutSession parameters: - $ref: '#/components/parameters/XAgentApiKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateCheckoutSessionRequest' example: scope: pivota.checkout responses: '200': description: Checkout JWT issued content: application/json: schema: $ref: '#/components/schemas/CheckoutSessionResponse' example: accessToken: user: id: 018f9a2b-7c3d-7e10-9a4b-2c1d5e6f7a8b abstractAccountAddress: 0x… '400': $ref: '#/components/responses/AirBadRequest' '401': $ref: '#/components/responses/AirUnauthorized' '403': $ref: '#/components/responses/AirForbidden' components: parameters: XAgentApiKey: name: x-agent-api-key in: header required: false description: > Opaque API key returned once at bind or rotate. Mutually exclusive with body `signedMessage`. Required for API-key-only agents. schema: type: string example: air_ag_… schemas: CreateCheckoutSessionRequest: type: object required: - scope additionalProperties: false properties: scope: type: string description: >- Merchant checkout target. `pivota.checkout` is currently the only supported value. enum: - pivota.checkout example: pivota.checkout signedMessage: allOf: - $ref: '#/components/schemas/AgentSignedMessage' description: | Mutually exclusive with `x-agent-api-key`. The bound key must have a stored public key. CheckoutSessionResponse: type: object required: - accessToken - user properties: accessToken: type: string description: > 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: $ref: '#/components/schemas/AgentUser' AgentSignedMessage: type: object required: - message - signature - publicKey properties: message: type: string description: >- Canonical proof `agent_pubkey:userId:unixEpochTime`, with the time in seconds. signature: type: string description: >- ECDSA P-256 signature over `message` (standard base64 or base64url; DER or IEEE P1363 / ES256). publicKey: type: string description: secp256r1 public key (PEM or base64 DER) that signed `message`. AgentUser: type: object required: - id properties: id: type: string format: uuid description: AIR user ID. abstractAccountAddress: type: string nullable: true description: The holder's AIR Account (smart account) address. example: 0x… AirError: type: object required: - code - message properties: code: type: string description: Machine-readable AIR API error code. enum: - INVALID_PARAMETER - UNAUTHORIZED - INVALID_TOKEN - AGENT_KEYS_DISABLED - AGENT_SCOPE_DENIED - AGENT_SCOPED_SESSION_DISABLED - CONFLICT_REQUEST - NOT_FOUND - INTERNAL_SERVER_ERROR message: type: string responses: AirBadRequest: description: Invalid request content: application/json: schema: $ref: '#/components/schemas/AirError' example: code: INVALID_PARAMETER message: scope is required AirUnauthorized: description: Missing or invalid partner session, partner JWT, or agent identity content: application/json: schema: $ref: '#/components/schemas/AirError' example: code: INVALID_TOKEN message: Unknown agent API key AirForbidden: description: >- Agent keys disabled for the partner, scope not a subset of the bound key, or `wallet.sign` on a partner route content: application/json: schema: $ref: '#/components/schemas/AirError' example: code: AGENT_KEYS_DISABLED message: Agent keys are not enabled for this partner ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.