Partner JWT security
- Private keys are stored in a secrets manager or HSM — never in source code or environment files checked into version control.
- JWTs are short-lived (
expset to 5 minutes or less). -
kidin the JWT header matches a key in your publicly accessible JWKS endpoint. - JWKS endpoint is served over HTTPS with a valid TLS certificate.
- JWTs are generated server-side only. The private key never reaches the client.
Authentication
- Use the authentication required by each surface: Partner JWT for SDK and direct AIR API operations,
x-api-keyfor issuer-hosted endpoints, andx-admin-api-keyfor self-hosted admin endpoints. - If using Custom Auth (BYO), verify the user’s identity in your own system before issuing the Partner JWT.
- Prompt for passkey MFA setup after login. MFA is required before wallet requests, and the abstract account address is returned only after setup unless you opt out.
- Set
skipRehydration: trueif your security model requires login on every session.
Credential issuance
- Validate credential data on your backend before signing and issuing. Do not trust client-supplied values.
- Dedupe issuance by recipient email + program ID; revoke the existing credential before reissuing when data changes (e.g. tier upgrades).
- For on-demand issuance, confirm DStorage returned a
storagePathor thatPOST /issue-vcsucceeded and the issuer persisted its DStorage result. - Sign credentials with issuer-controlled keys and encrypt them to the holder before DStorage upload. Keep raw source documents in issuer-controlled systems.
- Configure requested claims and proof requirements in the Verification Program; require user approval for disclosure.
Credential verification
- Generate a nonce of at least 128 bits on your backend for every verification, and delete it when you read it so it is used once.
- Verify the SD-JWT on your backend: trusted
issfrom your own allowlist, issuer signature, disclosure digests,exp, andvct. Never truststatusor the unsigned presentation wrapper. - Require the KB-JWT and check its signature against
cnf.jwk,nonce,aud(yourprogramId),iatfreshness, andsd_hash. - Check revocation through the issuer’s status endpoint or token status list, and fail closed if it cannot be fetched.
API security
- Use HTTPS for all API calls. Do not downgrade to HTTP, even in development.
- Implement retry logic with exponential backoff for transient failures (HTTP 500, network timeouts).
- Log API errors and monitor for unusual patterns (spikes in 401/403 responses may indicate key compromise).
- Rotate signing keys periodically. Update your JWKS endpoint before removing the old key.
Frontend security
- Do not expose your Partner ID’s private key on the client. The
partnerIditself is safe to include in client code. - Validate callback URLs and redirect URIs to prevent open-redirect attacks.
- AIR Kit loads its login flow in an iframe. If you set
Content-Security-Policy, allowframe-srcfrom*.air3.com. - If you enable CORS on your issuer service or a proxy in front of it, allow
*.air3.com, or the holder claim flow breaks.
Agentic integrations
- Show the user the agent and each requested scope, and record their approval before you bind. The bind request has no approval screen of its own.
- Bind only the scopes the user approved. Add
commerce.checkoutonly if the user wants the agent to start purchases. - Keep
agentApiKey, the partner login key, andx-partner-jwton your backend. - Create an agent session per operation with the narrowest scope it needs, and don’t cache agent JWTs beyond their 15-minute lifetime.
- When a user disconnects an agent, rotate the key and then revoke it, so outstanding sessions end too.
- Send checkout JWTs only to the merchant named in their
aud. Merchants must verifyaudand expiry. - Treat
502 CREDENTIAL_STORAGE_UNAVAILABLEas a retryable failure, not as “user not eligible”. - Enforce spending limits in the payment integration. AIR agent bindings do not carry payment authority.
Smart accounts and transactions
- Use the Paymaster for gas sponsorship. Monitor sponsorship spend to detect abuse.
- Validate transaction parameters on your backend before relaying to the user’s smart account.
- If using session keys, scope permissions to the minimum necessary operations and set short expiry times.
Monitoring
- Set up alerts for failed authentication attempts.
- Monitor credential issuance volumes for anomalies.
- Log user consent events for audit compliance.