A JWT can be easy to decode and still be invalid or unsafe to trust. This guide shows how to inspect a token, read its claims, separate parsing problems from signature-validation failures, and troubleshoot expiration, issuer, audience, algorithm, key-rotation, and authorization errors without exposing credentials.
Overview
JSON Web Tokens (JWTs) are compact strings commonly used to carry claims between an identity provider, an application, and an API. A typical signed JWT has three dot-separated parts:
header.payload.signature
The header identifies token metadata such as the signing algorithm and key identifier. The payload contains claims, such as the subject, issuer, audience, and expiration time. The signature allows a verifier with the correct key to determine whether the signed data is authentic and unchanged.
A JWT decoder can base64url-decode the header and payload, but decoding is not verification. Anyone who possesses a JWT can usually read its encoded claims; that does not mean the claims are trustworthy. Your API must validate the signature and apply its own checks before using the token for authentication or authorization.
When debugging, first identify which layer is failing:
- Transport: the token is missing, truncated, or sent in the wrong header format.
- Parsing: the value is not a correctly formatted JWT or contains invalid base64url data.
- Cryptographic validation: the signature cannot be verified with the expected key and algorithm.
- Claim validation: the token is structurally valid but expired, issued by the wrong authority, or intended for another service.
- Authorization: the token is valid, but its subject lacks the required role, scope, or permission.
This distinction prevents a common mistake: treating every 401 or 403 response as a signing problem.
What to track
1. Token structure and safe inspection
Begin with the exact token received by the application, not a copied or manually edited version. Confirm that it contains three segments separated by periods. Inspect it with a trusted local utility or a carefully selected JWT decoder tool. Do not paste production tokens into an online decoder unless your security policy explicitly permits it. A bearer token may grant access to APIs until it expires or is revoked, depending on the authentication design.
When logging during local or controlled testing, redact the signature and avoid recording the complete token. Prefer logging a request identifier, token hash, issuer, subject identifier where appropriate, and validation outcome. Never place access tokens in screenshots, tickets, chat messages, browser history, or long-lived CI logs.
2. Header fields
Review the header for:
alg: the algorithm declared by the token. The verifier should allow only algorithms configured for that issuer and endpoint.kid: the key identifier, if present. It helps the verifier select a public key during key rotation.typ: a type hint, often indicating a JWT. Do not treat it as a substitute for complete validation.
An algorithm mismatch can occur when the identity provider signs with one algorithm while the API is configured for another. Do not solve this by accepting arbitrary algorithms. Configure an explicit allowlist and follow the validation behavior recommended by the JWT library and identity provider.
3. Registered and application claims
| Claim | Meaning | Debugging question |
|---|---|---|
iss | Issuer that created the token | Does it exactly match the issuer configured for this environment? |
sub | Subject identified by the token | Is this the expected user, service, or client identifier? |
aud | Intended recipient or audience | Does it name this API rather than a different application? |
exp | Expiration time as a NumericDate | Was the request made before the token expired? |
nbf | Not-before time | Is the token being used before it becomes valid? |
iat | Issued-at time | Was it issued recently enough for the application’s policy? |
jti | Token identifier, when supplied | Is this token duplicated, revoked, or unexpectedly reused? |
scope, roles, or custom claims | Application permissions or identity data | Does the API map these claims to the required permission? |
Claims are data supplied by the token issuer, not instructions that should automatically override application policy. Validate expected types and values. For example, decide whether your library returns aud as a string, an array, or either, and test that behavior explicitly.
4. Signature and key selection
A validly decoded payload does not prove that the token came from your identity provider. Signature verification requires the correct public key for asymmetric algorithms or the correct shared secret for symmetric algorithms. Check the configured issuer, key set URL or key source, selected kid, algorithm allowlist, and environment-specific secrets.
During key rotation, an issuer may publish more than one key. A verifier that caches keys indefinitely can reject newly signed tokens; a verifier that refreshes on every request can create unnecessary dependency and availability problems. Use the library’s supported key-caching behavior, monitor key-refresh failures, and define an operational fallback rather than disabling signature checks.
Cadence and checkpoints
JWT debugging is usually incident-driven, but a small recurring review catches configuration drift before it becomes an outage. Add the following checkpoints to your engineering or platform routine.
During every integration or deployment
- Test a valid token, an expired token, a wrong-audience token, and a token signed with an unexpected key.
- Confirm that missing credentials produce an authentication response and insufficient permissions produce an authorization response according to your API contract.
- Verify that tokens are not printed in application, reverse-proxy, tracing, or CI logs.
- Check that the API uses the intended issuer and audience for the current environment.
Monthly or quarterly
- Review issuer metadata, signing-key configuration, algorithm allowlists, and key-refresh health.
- Inspect dashboards for increases in expired-token, invalid-signature, wrong-issuer, and insufficient-scope failures.
- Retest clock synchronization on hosts that issue or validate tokens.
- Review role and scope mappings after identity-provider, API, or organizational changes.
- Remove temporary debug logging and confirm that old test credentials have been revoked or deleted.
Keep this review alongside API contract checks and documentation. A defined OpenAPI governance workflow can make authentication requirements, security schemes, and expected error responses visible to client and service teams.
How to interpret changes
Use this decision tree when a request fails:
- Is the authorization header present and correctly formatted? For a bearer token, check for the expected scheme, whitespace, and absence of accidental quotation marks or line breaks. If not, fix the client or proxy first.
- Does the token have three readable segments? If not, investigate truncation, URL handling, cookie limits, or a client that is sending an opaque token instead of a JWT.
- Can the signature be verified? If no, compare
alg,kid, issuer configuration, key availability, and environment. Do not trust decoded claims while this step fails. - Do time claims pass? Compare
expandnbfwith the validator’s current UTC time. Small clock differences can matter, but allow only a deliberately configured clock-skew tolerance and monitor time synchronization. - Do issuer and audience match? A token issued for a web client, development environment, or different API may be valid but unusable for the current resource server.
- Does the subject have the required permission? If authentication succeeds but access is denied, inspect scope or role mapping, tenant checks, resource ownership, and application policy. This is commonly an authorization issue rather than a JWT parsing issue.
An expired-token error should normally lead the client to obtain a fresh token through its supported authentication flow, not to extend the expiration locally. A signature error should lead to configuration and key investigation, not to accepting unsigned tokens. A wrong-audience error should lead to checking client registration and API configuration, not to removing audience validation.
For reproducible tests, use a dedicated non-production identity provider tenant or test issuer. Record the token’s non-sensitive metadata, the validator configuration version, server time, and correlation ID. If the failure occurs across several services, compare their issuer, audience, clock, and key-cache settings rather than assuming the identity provider is solely responsible.
When to revisit
Return to this guide whenever an identity provider, JWT library, API gateway, signing algorithm, key-management process, or authorization model changes. It is also worth revisiting after a production authentication incident, a migration between environments, or the introduction of a new client type.
At a minimum, schedule a monthly or quarterly checkpoint for key rotation readiness, claim mappings, clock synchronization, and logging hygiene. Refresh the team’s test cases when terminology or validation defaults change in the identity platform or library. Keep examples aligned with the versions your services actually use; validation APIs and configuration names can differ between libraries.
For your next debugging session, save a redacted validation record containing the request ID, environment, issuer, audience, algorithm, key ID, validation stage, and time-related result. Then follow the decision tree from transport through authorization. This creates a useful operational history without retaining bearer credentials and turns JWT inspection from guesswork into a repeatable developer workflow.