Skip to main content
Use this checklist when integrating AIR Kit to ensure your implementation follows security best practices.

​
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 (exp set to 5 minutes or less).
  • kid in 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-key for issuer-hosted endpoints, and x-admin-api-key for self-hosted admin endpoints.
  • If using Custom Auth (BYO), verify the user’s identity in your own system before issuing the Partner JWT.
  • Enable MFA for high-value operations (credential issuance, large transactions).
  • Set skipRehydration: true if 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 direct issuance, confirm DStorage returned a storagePath. For hosted issuance, confirm POST /issue-vc succeeded and the issuer persisted its DStorage result.
  • If handling regulated data, enable CAK encryption.

​
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 partnerId itself is safe to include in client code.
  • Validate callback URLs and redirect URIs to prevent open-redirect attacks.
  • If embedding AIR Kit in an iframe, configure Content-Security-Policy headers to allow frame-src from AIR Kit domains.

​
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 (CAK authorizations) for audit compliance.