Skip to main content
These are the issues most AIR Kit integrations run into first. To look up a specific HTTP status or SDK error code, see Error codes. For platform-specific problems, see Web and Flutter. For issuance, verification, and schema problems, see Identity & Credential.

JWT and JWKS errors

”Invalid signature” or “JWT verification failed”

  • Confirm the kid in your JWT header matches a key ID in your JWKS endpoint.
  • Verify the algorithm (RS256 or ES256) matches the key type in your JWKS.
  • Check that you are signing with the correct private key.

”Token expired”

  • The exp claim has passed. Generate a new JWT with a fresh exp (recommended: 5 minutes from now).
  • Verify your server clock is synchronized (NTP).

”JWKS endpoint unreachable”

  • Your JWKS URL must be publicly accessible over HTTPS — AIR servers cannot reach localhost. Use an HTTPS tunnel (ngrok, cloudflared) or deploy.
  • Test the exact URL registered in the Developer Dashboard, not a guess. For example:
  • air-examples ships /api/.well-known/jwks; the plug-and-play template ships /jwks.json. Register whichever your app actually serves.
  • Ensure no firewall or IP allowlist blocks AIR servers.
  • Full setup procedure: JWKS endpoint setup.

dStorage returns “Invalid x-partner-auth”

POST /dstorage/vcs validates the x-partner-auth Partner JWT against the JWKS URL registered for your Partner ID. When the claims (partnerId, scope: "issue", exp) and the typ: "JWT" header are already right:
  • Fetch the exact JWKS URL from the Dashboard and confirm it returns your live public keys, not an old tunnel, a placeholder, or a cached copy.
  • Confirm the token header kid appears in that document and that its public key matches the private key that signed the token.

”kid not found”

  • The kid in your JWT header does not match any key in the JWKS response.
  • If you recently rotated keys, publish the new key to your JWKS endpoint before using it in JWTs.

”Missing typ header”

  • For server-side issuance, the JWT header must include typ: "JWT". Add it to your JWT signing options:

AIR Kit does not load on localhost

AIR Kit only runs on HTTPS origins whitelisted under Account → Domains, so it fails on http://localhost and other plain-HTTP origins in every environment. Run your app behind an HTTPS tunnel, whitelist the tunnel domain under Account → Domains, and open the app at the tunnel URL. If the tunnel URL changed since you whitelisted it, whitelist the new domain, remove the old one, and update the JWKS URL.

CORS errors

If you see CORS errors when initializing the SDK in a browser:
  • AIR Kit uses an iframe for login. Ensure your Content-Security-Policy allows frame-src from *.air3.com.
  • If you are proxying requests, ensure the Origin header is forwarded correctly.

Rate limiting

API endpoints may return 429 Too Many Requests if you exceed rate limits. Back off and retry with exponential delays. Avoid tight polling loops on the status endpoint — start with 1-second intervals and double each attempt.