Skip to main content
The Agent APIs let your backend act for a holder, the signed-in user, through a bound agent. You bind an agent once, then mint a short-lived agent JWT for each operation and use it to list or verify the holder’s credentials. If the agent’s key includes checkout, you can also mint a token for a merchant checkout. For a step-by-step walkthrough with request examples, see the Using Agentic Identity. Get the user’s approval before you bind an agent; the bind request has no approval step of its own. See Ask for consent before binding.

​
Base URLs

The Agent APIs span two hosts. Use the pair for the same environment.
Agent keys must be enabled for your partner account. Otherwise, AIR API calls return 403 AGENT_KEYS_DISABLED. Contact the AIR team to enable agent keys and confirm which environment is available for your integration.

​
Authentication

Each route uses a different combination of headers. Sign x-partner-jwt on your backend with the same key you use for AIR Kit login. Its partnerId must match x-partner-id and the holder’s session. See SDK authentication for key setup. Session and checkout creation accept exactly one agent identity: the x-agent-api-key header, or a signedMessage in the body for agents bound with a P-256 public key.
Treat agentApiKey and x-partner-jwt as backend secrets. Never send them to a browser or embed them in page JavaScript.

​
Scopes

Bind an agent with a space-delimited scope. AIR adds openid automatically. Partner bind cannot include wallet.sign. A session can request a subset of the bound scopes; omit scope to receive all of them.

​
Tokens and key lifecycle

Rotating a key returns a new agentApiKey and invalidates agent JWTs already issued for that key. Revoking a key stops new sessions for it.

​
Errors

Errors return a JSON body with a machine-readable code and a message. AIR API codes: INVALID_PARAMETER, UNAUTHORIZED, INVALID_TOKEN, AGENT_KEYS_DISABLED, AGENT_SCOPE_DENIED, AGENT_SCOPED_SESSION_DISABLED, CONFLICT_REQUEST, NOT_FOUND, and INTERNAL_SERVER_ERROR. Credential API codes: INVALID_PARAMETER, UNAUTHORIZED, FORBIDDEN, CREDENTIAL_STORAGE_UNAVAILABLE, and VERIFICATION_PROGRAM_NOT_FOUND. A 502 CREDENTIAL_STORAGE_UNAVAILABLE on verify means storage could not be read. It does not mean the holder lacks the credential; that case returns 200 with status: "NotFound".

​
Endpoints

Bind an agent

Register an agent for the holder and receive its API key once.

Create an agent session

Mint a 15-minute agent JWT.

List credentials

Page through the holder’s credentials with optional filters.

Verify a credential

Run a verification program and receive a presentation when compliant.

Create a checkout session

Mint a token for a supported merchant checkout.

Manage agent keys

List, rename, rotate, and revoke bound agents.