> ## 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 an agent session > Issues a **15-minute** access token (`type=agent`) with no refresh token. Create one per operation. Identify the agent with **exactly one** of the `x-agent-api-key` header or the body `signedMessage`. API-key-only agents must use the header. `signedMessage` requires a public key stored at bind time. The requested `scope` must be a subset of the bound key's scopes; omit it to receive the full bound set. Tokens issued before a key rotation fail. ## OpenAPI ````yaml api-reference/agent-openapi.json POST /v2/auth/agent/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/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 session summary: Create an agent session description: > Issues a **15-minute** access token (`type=agent`) with no refresh token. Create one per operation. Identify the agent with **exactly one** of the `x-agent-api-key` header or the body `signedMessage`. API-key-only agents must use the header. `signedMessage` requires a public key stored at bind time. The requested `scope` must be a subset of the bound key's scopes; omit it to receive the full bound set. Tokens issued before a key rotation fail. operationId: createAgentSession parameters: - $ref: '#/components/parameters/XPartnerId' - $ref: '#/components/parameters/XAgentApiKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateAgentSessionRequest' example: scope: openid credentials.read credentials.verify responses: '200': description: Agent JWT issued content: application/json: schema: $ref: '#/components/schemas/AgentSessionResponse' 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: XPartnerId: name: x-partner-id in: header required: true description: Your Partner ID (UUID) from the Developer Dashboard. schema: type: string format: uuid 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: CreateAgentSessionRequest: type: object additionalProperties: false properties: scope: type: string description: > Space-delimited scopes for the agent JWT. Must be a subset of the bound key's scopes. Omit to use the full bound set. example: openid credentials.read credentials.verify signedMessage: allOf: - $ref: '#/components/schemas/AgentSignedMessage' description: | Mutually exclusive with `x-agent-api-key`. The bound key must have a stored public key. AgentSessionResponse: type: object required: - accessToken - user properties: accessToken: type: string description: >- Agent JWT (`type=agent`), valid for 15 minutes. Send as `Authorization: Bearer`. 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.