JWT and JWKS errors
”Invalid signature” or “JWT verification failed”
- Confirm the
kidin your JWT header matches a key ID in your JWKS endpoint. - Verify the algorithm (
RS256orES256) matches the key type in your JWKS. - Check that you are signing with the correct private key.
”Token expired”
- The
expclaim has passed. Generate a new JWT with a freshexp(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-examplesships/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
kidappears in that document and that its public key matches the private key that signed the token.
”kid not found”
- The
kidin 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 onhttp://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-Policyallowsframe-srcfrom*.air3.com. - If you are proxying requests, ensure the
Originheader is forwarded correctly.
Rate limiting
API endpoints may return429 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.