A valid request URL is required to generate request examples{
"id": "3f1a9c8e-2b7d-4f60-a1c5-e9b8d7f6a4c2",
"publicKey": null,
"createdAt": "2026-08-19T12:00:00.000Z",
"scope": "openid credentials.read credentials.verify",
"nickname": "Shopping agent",
"partnerId": "11111111-2222-4333-8444-555555555555",
"agentApiKey": "air_ag_<secret>"
}{
"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"
}{
"code": "CONFLICT_REQUEST",
"message": "Maximum agent keys per user reached"
}Bind an agent
Registers an agent key for the holder authenticated by the partner access
token. Call this once per agent. publicKey is optional; omit it for
API-key-only agents.
agentApiKey is returned once. Store it on your backend.
A valid request URL is required to generate request examples{
"id": "3f1a9c8e-2b7d-4f60-a1c5-e9b8d7f6a4c2",
"publicKey": null,
"createdAt": "2026-08-19T12:00:00.000Z",
"scope": "openid credentials.read credentials.verify",
"nickname": "Shopping agent",
"partnerId": "11111111-2222-4333-8444-555555555555",
"agentApiKey": "air_ag_<secret>"
}{
"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"
}{
"code": "CONFLICT_REQUEST",
"message": "Maximum agent keys per user reached"
}Authorizations
The holder's AIR Kit partner access token, from airService.getAccessToken().
Send it with x-partner-id.
JWT signed with your partner login key (the same key used for the AIR Kit
login partnerJwt). Its partnerId must match x-partner-id and the
AIR Kit session. Omit email unless it is this holder's. Body partnerJwt
is accepted as a fallback.
Headers
Your Partner ID (UUID) from the Developer Dashboard.
Body
Space-delimited scopes. openid is added automatically. Allowed:
credentials.read, credentials.verify, commerce.checkout. Partner
bind cannot include wallet.sign.
"credentials.read credentials.verify"
Display name (letters, numbers, spaces, hyphens, colons; maximum 32
characters). Defaults to Agent YYYY-MM-dd HH:mm:ss (UTC).
32"Shopping agent"
secp256r1 (P-256) public key, PEM or base64 DER. Required only when the
agent will create sessions with signedMessage.
"-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE…\n-----END PUBLIC KEY-----\n"
Response
Agent bound. agentApiKey is returned only this once.
Space-delimited scopes granted to the key, including openid.
"openid credentials.read credentials.verify"
Opaque secret with the prefix air_ag_. Returned only once.
"air_ag_<secret>"
Masked PEM when a public key was bound; null for API-key-only agents.
Was this page helpful?