A JWT can be decoded in seconds, but decoding does not prove that a token is authentic or safe to use. This guide provides a repeatable workflow for diagnosing rejected, expired, or unexpectedly accepted JSON Web Tokens: inspect claims without trusting them, verify issuer and audience, confirm algorithm and signature behavior, investigate JWKS and key-rotation failures, and establish recurring checks for authentication code and configuration.
Overview
JWT debugging has two separate tasks that are often confused. The first is inspection: reading the token header and payload to understand what a client or service sent. The second is validation: proving that the token was issued by the expected authority, has not expired, is intended for this service, and has a valid signature under an allowed algorithm.
A JWT normally has three Base64URL-encoded parts separated by periods:
- Header: metadata such as the signing algorithm (
alg) and key identifier (kid). - Payload: claims such as issuer, subject, audience, expiration, and scopes.
- Signature: a cryptographic value used to verify that the signed content was not altered and was produced by a trusted key.
Use a JWT decoder or local Base64URL tooling to inspect a token only when it is appropriate to handle that token. Treat every decoded field as untrusted input until verification succeeds. Never paste production access tokens, refresh tokens, session tokens, or tokens containing personal data into an online utility unless your security policy explicitly permits it. A decoder reveals content; it does not validate the signature, identify the correct issuer, or make an unsafe token safe.
For an incident or a recurring review, record the token issuer, client or service involved, authentication library and version, configured algorithms, key-set endpoint, and the observed error. Redact the token itself in tickets and logs. A hash of the token or a short, non-sensitive correlation identifier is usually more useful than the complete credential.
What to track
Claims and their expected meaning
Compare the decoded claims with the contract defined by the identity provider and the receiving service. The following claims are common, but not every token includes all of them and their exact semantics depend on the integration.
| Claim | What to check | Typical failure |
|---|---|---|
iss | Matches the exact configured issuer, including scheme, host, path, and sometimes trailing-slash behavior. | The service trusts a different tenant, realm, or issuer URL. |
aud | Contains the identifier expected by the receiving API. It may be a string or an array. | A token for one API is presented to another API. |
exp | Is in the future, using seconds since the Unix epoch and a documented clock-skew policy. | The token is expired, or the validator's clock is incorrect. |
nbf | Has passed before the token is accepted. | The token is being used before its intended start time. |
iat | Is plausible for the authentication flow and does not indicate a future-issued token without an explanation. | Issuer and verifier clocks differ, or a test fixture is malformed. |
sub | Maps to the expected user, workload, or service identity. | Authorization uses the wrong identity field or assumes an unstable format. |
scope, roles, or permissions | Match the authorization contract for the endpoint. | Authentication succeeds but authorization fails, or claims are interpreted with the wrong delimiter or namespace. |
Do not authorize a request merely because a claim is present. The application must first complete signature and registered-claim validation. It should also enforce the expected token type and credential location for the protocol flow. For example, an API should have a clear rule about whether it accepts a bearer token in the HTTP Authorization header and should avoid accepting credentials through ambiguous alternative locations.
Header, algorithm, and key metadata
Inspect alg and kid, then compare them with the verifier's allowlist and the issuer's published keys. The algorithm must be selected by trusted configuration, not accepted simply because the token declares it. Do not enable an unsecured algorithm for production authentication, and take particular care when a library supports both symmetric algorithms, such as HMAC, and asymmetric algorithms, such as RSA or elliptic-curve signatures. A configuration that treats a public key as an HMAC secret can create a serious verification flaw.
A missing or unknown kid often indicates a key-rotation or environment mismatch. Check whether the verifier can reach the configured JWKS endpoint, whether the issuer published the new key, whether the token uses the expected key identifier, and whether a proxy or cache is serving stale key material. A successful key lookup does not remove the need to verify issuer, audience, algorithm, and signature.
The actual validation result
Capture the precise validation error rather than reporting only “JWT invalid.” Useful categories include malformed token, missing bearer credential, unsupported algorithm, signature mismatch, unknown key ID, issuer mismatch, audience mismatch, not-before failure, expiration, and insufficient scope. Keep these details in controlled diagnostics because verbose authentication errors can disclose information to an untrusted caller.
Cadence and checkpoints
A JWT validation review is most effective when it is part of normal developer tooling and platform operations rather than a one-time troubleshooting exercise. Use the following checkpoints as a practical monthly or quarterly routine, and repeat them immediately after identity-provider, library, or deployment changes.
- Monthly: inspect authentication error trends by service, issuer, audience, error category, and deployment version. Look for a rise in expired tokens, unknown key IDs, or signature failures after a release.
- Monthly: verify that production clocks are synchronized and that the documented clock-skew allowance is narrow enough for the environment. Do not compensate for chronically incorrect clocks by accepting very old or future-dated tokens.
- Quarterly: review algorithm allowlists, issuer and audience configuration, token lifetimes, refresh-token handling, and the permissions granted to service accounts. Remove algorithms, issuers, and audiences that are no longer needed.
- Quarterly: rehearse a signing-key rotation in a non-production environment. Test overlap between old and new keys, JWKS caching behavior, application restart behavior, and the response when an old key is removed.
- After every relevant change: run tests with valid, expired, future-dated, wrong-audience, wrong-issuer, altered-payload, unsupported-algorithm, and unknown-
kidtokens. Confirm that failures are rejected consistently and that logs contain a safe diagnostic reason.
Store the expected values in configuration or a service catalog rather than relying on tribal knowledge. An internal developer platform can expose the owning team, issuer, audience, key endpoint, and rotation contact for each API. This complements broader service ownership practices described in the Backstage software catalog guide.
How to interpret changes
Start with the boundary at which the failure occurs. If no token reaches the service, investigate client configuration, authorization-header formatting, proxies, and gateway behavior. If the token is parsed but fails validation, compare the token's issuer, audience, timestamps, algorithm, and key ID with the verifier's configuration. If validation succeeds but the request is denied, investigate scopes, roles, resource ownership, and application authorization rules instead of changing cryptographic settings.
A sudden increase in unknown key ID errors usually points to rotation timing, stale JWKS caches, an incorrect issuer environment, or a token minted by a different identity system. A rise in signature mismatch errors can indicate altered tokens, a wrong key set, a signing-key configuration problem, or inconsistent algorithm settings. Treat it as a security-relevant signal and preserve relevant deployment and key-rotation evidence.
Repeated expired-token failures may be normal for clients that do not refresh credentials correctly, but they can also reveal clock drift or an unsuitable token lifetime. Do not solve the problem by disabling expiration checks. Check refresh behavior, retry loops, system time, and the relationship between access-token lifetime and request duration.
When reproducing a failure, create a minimal development fixture with a known issuer, audience, signing key, and timestamps. Test the receiving service with one variable changed at a time. Never use a copied production token as a test fixture. Add these cases to CI so a dependency upgrade or configuration change cannot silently weaken validation. For supply-chain and release controls around authentication code, the software supply chain security guide provides related workflow context.
Use telemetry carefully. Metrics can count validation categories without recording token contents, while traces can carry a request or authentication correlation ID rather than claims or credentials. If authentication failures are part of a wider incident, connect them with service health and deployment evidence using an observability approach such as the one outlined in the OpenTelemetry setup guide.
When to revisit
Revisit this guide on a monthly or quarterly cadence, and immediately when any of the following occurs: a signing key is added or revoked; a JWKS endpoint, issuer, tenant, or audience changes; an authentication library or API gateway is upgraded; a new client or service is onboarded; token lifetimes or scopes change; a service moves between environments; or an incident involves unexpected claims, rejected signatures, or unauthorized access.
Before closing a review, complete this short checklist:
- Decode only in an approved, non-production workflow and treat decoded content as untrusted.
- Confirm the exact issuer and expected audience.
- Validate the signature with a trusted key and an explicit algorithm allowlist.
- Check
exp,nbf, and clock synchronization using a documented skew policy. - Test JWKS reachability, caching, unknown key IDs, and key-rotation overlap.
- Separate authentication failures from authorization failures.
- Keep tokens and sensitive claims out of logs, tickets, screenshots, and shared online utilities.
- Record the owner, expected configuration, test cases, and next review date.
Make the checklist part of release validation and incident runbooks. A JWT decoder is useful for understanding what was sent; a controlled validation workflow is what establishes whether the request should be trusted.