A JWT can look structurally correct and still fail authentication. This guide provides a repeatable debugging workflow for safely inspecting claims, checking expiration and clock settings, distinguishing decoding from signature validation, and documenting fixes across local, staging, and production environments.
Overview
JSON Web Tokens (JWTs) are commonly used to carry authentication and authorization data between an application, an identity provider, and an API. A token usually contains three Base64URL-encoded sections separated by periods: a header, a payload, and a signature. The header identifies token metadata such as the signing algorithm. The payload contains claims, such as the subject or expiration time. The signature allows a validating service to check that the signed content has not been altered.
When a login request fails, the token itself is only one part of the investigation. The request may contain the wrong authorization scheme, the API may expect a different issuer or audience, the signing key may be unavailable, or the server clock may disagree with the token issuer. A decoder can help you inspect the header and payload, but decoding alone does not prove that a token is authentic or acceptable.
Use this workflow in a controlled environment. Never paste production tokens, refresh tokens, API keys, or other credentials into an untrusted JWT decoder online. If a token has been exposed, treat it as potentially compromised and follow your organization’s token-revocation or rotation procedure.
What to track
Start by recording the complete failure context without storing the secret token. Save the request method, route, environment, response status, server time, client time, identity provider, and a short-lived token identifier if your system provides one. Redact the token value in logs; in many cases, the first few characters are enough to correlate a test request, but even that practice should follow your logging policy.
JWT claim reference
| Field | Purpose | Debugging question |
|---|---|---|
iss | Identifies the issuer that created the token. | Does it exactly match the issuer configured by the API, including scheme and path? |
aud | Identifies the intended recipient or resource. | Does the API expect this audience, and is its type a string or an array as expected? |
sub | Identifies the authenticated subject. | Can the application map this subject to a user, service account, or permission record? |
exp | Sets the time after which the token must not be accepted. | Has the expiration passed, or is a unit conversion causing an incorrect comparison? |
nbf | Sets the earliest time at which the token is valid. | Is the server attempting to use the token before this time? |
iat | Records when the token was issued. | Does it reveal a clock mismatch or an unexpectedly old token? |
jti | Provides a token identifier when included. | Is the token revoked, replayed, or already recorded by a denylist? |
The exp, nbf, and iat values are commonly represented as numeric time values rather than readable dates. Confirm the unit expected by your library and compare the converted value with the server’s current time. Do not “fix” an expiry error by disabling validation. Instead, correct the token lifetime, renewal flow, or clock configuration.
Check the request before the token
Verify that the request sends the header in the form expected by the API, typically Authorization: Bearer <token>. Look for accidental quotation marks, extra whitespace, line breaks, URL encoding, a copied refresh token instead of an access token, or a proxy that strips the header. Compare a failing request with a known-good request while keeping the token values redacted.
Also inspect the JWT header for the algorithm and key identifier. An algorithm mismatch, missing key identifier, unavailable signing key, or stale key cache can cause validation to fail even when the payload appears reasonable. Never select a verification algorithm solely because the token declares it; the server should allow only algorithms configured for that issuer and application.
Cadence and checkpoints
JWT troubleshooting is most effective when treated as a recurring operational check rather than a one-time inspection. During local development, test a fresh login, an expired access token, a token with the wrong audience, and a request with no authorization header. These cases help confirm that the application returns a safe, consistent error without revealing validation details.
Before a deployment or identity-provider migration, compare the configured issuer, audience, signing algorithms, key-discovery endpoint, token lifetimes, and required claims between environments. Check both the application that creates the token and the service that validates it. If an API is part of an AI application, include authentication tests for model endpoints, retrieval services, background workers, and administrative routes rather than testing only the web login.
On a monthly or quarterly schedule, review authentication logs for recurring patterns: spikes in expired-token responses, failures concentrated on one service, unknown key identifiers, issuer mismatches, or requests from systems with inconsistent time. The appropriate cadence depends on your risk and release schedule, but a regular review makes configuration drift easier to detect.
For scheduled jobs and token-renewal workers, document the timezone and retry behavior separately from JWT validation. A job that runs at the wrong local time can repeatedly use an expired credential or renew too late. The cron expression guide can help when authentication failures appear tied to recurring automation.
How to interpret changes
Classify the failure before changing code. A malformed-token error often points to a damaged, truncated, incorrectly copied, or incorrectly formatted token. An expiration or not-before error points to time, lifetime, or renewal behavior. An issuer or audience error usually indicates that the client received a token for a different API or environment. A signature or key error suggests a signing-key, algorithm, key identifier, or key-discovery problem. A successful token validation followed by a forbidden response usually indicates an authorization or scope problem rather than an authentication problem.
Clock skew deserves special attention. Compare the system time on the client, API server, identity provider, container, and any gateway involved in the request. Small validation tolerances may be appropriate for known infrastructure differences, but a large tolerance can extend the usable lifetime of a token and hide an operational problem. Record the chosen tolerance and test it during deployment reviews.
Do not confuse decoding with verification. Base64URL decoding reveals readable claims but does not confirm who issued the token or whether its contents were modified. Verification requires the appropriate cryptographic key, allowed algorithm, and policy checks for issuer, audience, time, and required claims. Likewise, a valid signature does not automatically grant access; the application must still evaluate scopes, roles, tenant boundaries, and resource permissions.
Authentication troubleshooting checklist
- Redact the token and record the route, environment, status code, and request time.
- Confirm the authorization header format and ensure the access token is being used.
- Decode only in a controlled environment and inspect the header and payload.
- Compare
iss,aud,exp,nbf, and required claims with the API configuration. - Check server clocks, timezone assumptions, and any configured clock-skew tolerance.
- Confirm the algorithm, key identifier, signing key, and key rotation behavior.
- Separate authentication failures from authorization failures such as missing scopes.
- Reproduce with a newly issued token, then test renewal and logout behavior.
Keep an incident worksheet with these fields: date and environment; affected route; redacted token identifier; issuer and audience; relevant time claims; client and server times; observed status and error category; configuration changes; reproduction result; and final fix. This record turns a recurring incident into a useful regression test. For broader API failures, pair it with a documented retry and validation strategy such as the patterns in the AI API error handling guide.
When to revisit
Revisit this checklist whenever authentication libraries, framework defaults, identity providers, signing algorithms, key-rotation processes, or token schemas change. It should also be part of the review for a new deployment environment, a domain or audience change, a token-renewal update, a gateway migration, or a production incident involving unauthorized or rejected requests.
At each monthly or quarterly review, select a small set of representative flows: fresh login, expired access token, early-use token, wrong audience, rotated signing key, missing header, and insufficient permission. Confirm that the expected response remains safe and that logs contain enough redacted context to diagnose the issue. Refresh examples and library-specific instructions when implementation behavior changes; avoid assuming that a decoder’s output is equivalent to a validator’s result.
For the next incident, begin with the worksheet rather than immediately changing token lifetimes or disabling checks. Capture the failing request, compare claims against the configured expectations, verify time and key material, reproduce with a controlled token, and document the smallest safe fix. This process makes JWT authentication debugging repeatable for both conventional web services and AI applications that depend on protected APIs.