A JWT failure can come from an expired claim, a mismatched audience, a rotated signing key, or a simple misunderstanding of what decoding proves. This guide provides a reusable JWT debugging checklist for AI APIs, including safe inspection, claim verification, signature troubleshooting, and checks for common integration errors.
Overview
A JSON Web Token (JWT) usually has three dot-separated parts: a header, a payload, and a signature. The header identifies details such as the signing algorithm and, sometimes, a key identifier. The payload contains claims about the token, such as its issuer, subject, audience, and validity period. The signature is used to verify that the signed content has not been changed and that it was produced by a trusted signer.
These parts are encoded, not encrypted, in a typical signed JWT. Anyone who obtains the token may be able to decode the header and payload, so access tokens should never contain secrets or sensitive information merely because they are inside a JWT. A decoder is useful for inspection, but decoding alone does not establish that a token is authentic, current, or acceptable to an API.
When debugging an AI API, separate the problem into three questions:
- Can the token be parsed? Check its structure and JSON content.
- Is the token valid? Check its signature, algorithm, issuer, audience, and time-based claims.
- Will this API accept it? Confirm the required authorization header, scopes, permissions, token type, and provider-specific authentication flow.
JWT claims reference
| Claim or field | What to inspect | Typical debugging question |
|---|---|---|
alg | Signing algorithm in the header | Does it match the verifier configuration? |
kid | Key identifier, when present | Can the verifier find the corresponding public key? |
iss | Issuer | Is this token issued by the expected identity service? |
aud | Audience | Was the token intended for this API? |
sub | Subject or principal | Which user, service, or application does it represent? |
exp | Expiration time, represented as a numeric date | Has the token expired according to the verifier's clock? |
nbf | Not-before time, when present | Is the token being used before it becomes valid? |
iat | Issued-at time | Was it issued recently enough for the intended flow? |
scope or permissions | Provider-specific authorization data | Does the token allow the requested operation? |
Checklist by scenario
When you need to inspect a token
- Capture the token only in a controlled debugging environment. Do not paste a live production token into a public JWT decoder or an unapproved third-party service.
- Confirm that the value has three dot-separated segments. A token with a missing segment may be truncated, copied incorrectly, or may not be a JWT at all.
- Decode the header and payload as Base64URL-encoded JSON. This step is for visibility only; it does not verify the signature.
- Record the algorithm, key identifier, issuer, audience, expiration, not-before time, and relevant scopes. Redact the token before sharing logs or screenshots.
A safe redaction might preserve the shape without exposing the credential: eyJ...header-redacted...abc.def...payload-redacted...xyz.signature-redacted. Prefer logging a token fingerprint, request ID, or last few characters rather than the complete token.
When the API reports an expiration error
- Read the
expvalue as a numeric date and compare it with the server's current UTC time. - Check
nbfas well. A token can be rejected because it is not valid yet, even when its expiration is in the future. - Compare the clocks on the token issuer, your application host, containers, and API gateway. Small clock differences can matter near a boundary.
- Check whether a cached token is being reused after its intended lifetime. Refresh tokens according to the provider's documented flow rather than repeatedly retrying the same access token.
- Distinguish an expired JWT from an expired API key, session, or credential used to obtain the JWT. The error may come from a different authentication layer.
When signature verification fails
- Confirm that the token was not altered by copying, URL decoding, whitespace insertion, or a proxy that changed the authorization value.
- Compare the header's
algwith the algorithm explicitly allowed by the verifier. Do not select verification behavior solely from untrusted token input. - For symmetric signing such as HS256, confirm that both sides use the same secret and expected encoding.
- For asymmetric signing such as RS256, confirm that the verifier has the correct public key and that the key corresponds to the token's
kid. - If the provider publishes a JWKS endpoint, check whether key rotation or a stale key cache explains the failure. Refresh keys according to a controlled cache policy, not on every arbitrary request.
When the signature is valid but the API still returns unauthorized
- Verify the
issvalue exactly. A token from a development tenant, realm, or identity environment may be cryptographically valid but unacceptable to production. - Verify
aud. The token may be intended for a different service, resource server, or API version. - Check scopes, roles, permissions, and subject restrictions required for the endpoint.
- Confirm the request uses the provider's required format, commonly an
Authorization: Bearer <token>header, but do not assume every AI API uses the same scheme. - Check whether the endpoint expects a JWT at all. Some services use API keys, short-lived provider tokens, signed requests, or an SDK-managed credential instead.
Signing and verification comparison
| Approach | Key model | Debugging focus |
|---|---|---|
| HS256 | One shared secret signs and verifies | Secret value, encoding, configuration, and safe secret handling |
| RS256 | Private key signs; public key verifies | Correct public key, algorithm restrictions, and issuer configuration |
| JWKS-based verification | Verifier retrieves public keys from a key set | kid matching, key rotation, endpoint access, and cache freshness |
What to double-check
Before changing code, compare the failing request with a known-good request. Record the HTTP method, URL host, authorization scheme, relevant headers, response status, provider error code, and a request or trace identifier. Remove credentials and personal data from the comparison.
Check the entire authentication path rather than only the token. An AI application may have an identity provider, an API gateway, a service account, an SDK, and the model service itself. A valid token can fail because the gateway forwards the wrong header, the SDK uses a different environment variable, or the requested model operation requires a permission not present in the token.
Use a real verification library in application code. A local decoder or Base64URL utility is appropriate for examining claims, but production authorization should validate the signature and enforce expected algorithms, issuer, audience, and time claims. Configure accepted values explicitly where the library permits it.
For incident records, save the token's non-sensitive metadata, verification result, key identifier, clock time, and correlation ID. Avoid saving the raw token unless your security process specifically permits it and access is tightly controlled.
Common mistakes
- Confusing decoding with verification: Readable payload JSON proves only that the token can be decoded.
- Trusting claims before checking the signature: Treat all decoded claims as untrusted until verification succeeds.
- Ignoring audience and issuer: A valid token issued for another service is not automatically valid for your API.
- Accepting any algorithm: Restrict verification to the algorithms your integration is designed to use.
- Logging complete bearer tokens: Tokens in logs, tickets, shell history, or screenshots can become credentials.
- Retrying an expired token indefinitely: Refresh or reauthenticate through the intended flow, then surface a clear failure if that process cannot succeed.
- Assuming every provider uses identical claims: Standard registered claims are common, but scopes, roles, token types, and authentication requirements vary by provider.
- Blaming the model request first: Authentication failures usually need to be isolated from prompt, payload, rate-limit, and model-availability errors.
When to revisit
Return to this checklist whenever an AI API changes its authentication flow, signing keys rotate, an SDK or gateway is upgraded, a deployment moves between environments, or a token begins failing without an application-code change. It is also useful before a seasonal planning cycle or any release that changes service accounts, scopes, model access, or request routing.
As a practical final check, run this sequence before escalating an authentication incident:
- Confirm the credential type and authorization header.
- Inspect the JWT structure without exposing the raw token.
- Check
exp,nbf, and clock synchronization. - Verify the signature with an explicitly allowed algorithm and the correct key.
- Validate issuer, audience, subject, scopes, and provider-specific requirements.
- Compare the request with a known-good environment and capture a correlation ID.
- Rotate or revoke exposed credentials and remove sensitive tokens from logs or tickets.
Keep the checklist beside your API integration runbook, and update its library commands and provider requirements when your workflow changes. The durable principle is simple: decode to inspect, verify to trust, and authorize only after the token satisfies the API's complete requirements.