JWT debugging is easier when you separate token inspection from trust decisions. This guide provides a reusable checklist for decoding claims, validating signatures, diagnosing 401 responses, reproducing expiration failures, and responding safely when signing keys or token configuration change.
Overview
A JSON Web Token (JWT) is commonly represented as three dot-separated, Base64URL-encoded parts: a header, a payload, and a signature. The header describes the token type and signing algorithm. The payload contains claims about the subject, issuer, audience, timing, or permissions. The signature allows a verifier to check whether the signed content was produced with the expected key and has not been altered.
Decoding is not the same as validation. A JWT decoder, including a JWT decoder online, can make the header and payload readable, but it does not prove that the token is authentic. The payload is normally readable by anyone who possesses the token, so it should not contain secrets. Treat access tokens, refresh tokens, authorization headers, and copied production logs as sensitive credentials.
| Part | What it contains | What to check |
|---|---|---|
| Header | Token metadata, usually including typ and alg | Is the algorithm expected and explicitly allowed by the verifier? |
| Payload | Claims such as iss, sub, aud, exp, and nbf | Do the issuer, audience, subject, and time claims match the API's requirements? |
| Signature | A cryptographic value covering the header and payload | Does verification succeed with the correct trusted key and algorithm? |
In a corporate web application, a failed request can result from several layers: the browser may send the wrong token, the API may use a different issuer or audience, the token may be outside its valid time window, or the service may have stale signing keys. Start with evidence from the request and the API's authentication logs, then narrow the problem without exposing the credential.
Checklist by scenario
Scenario 1: Inspecting a token safely
- Capture only a development or deliberately test token whenever possible. Do not paste a production token into a public decoder or an unapproved third-party service.
- Confirm that the value has the expected form: three non-empty segments separated by periods for a signed JWT.
- Decode the header and payload locally or in an approved internal tool. Base64URL decoding reveals representation; it does not validate authenticity.
- Record the claim names and values needed for diagnosis, but redact the token itself from tickets, screenshots, chat messages, and application logs.
- Compare the token's issuer, audience, signing algorithm, and timing claims with the API configuration and identity-provider settings.
For local inspection, use a JWT library or a small, reviewed diagnostic script that performs Base64URL decoding without sending data over the network. A general-purpose OpenAPI contract-testing workflow can help confirm which security scheme and authorization header an API expects.
Scenario 2: Validating a signature
- Identify whether the token uses a symmetric or asymmetric signing method. Symmetric validation requires a shared secret; asymmetric validation uses a public key corresponding to the issuer's private signing key.
- Allow-list the algorithms your service is designed to accept. Do not select a verification method solely from the untrusted
algvalue in the token header. - Obtain the trusted key from the configured identity-provider metadata or key set, using the platform's supported key-discovery and caching behavior.
- Verify the signature over the original encoded header and payload. Do not decode, reserialize, or modify claims before verification.
- Only after signature verification succeeds, evaluate authorization-relevant claims and grant access.
A successful signature check does not automatically mean the request is authorized. The token may be authentic but intended for another service, issued by an untrusted authority, expired, or missing the required scope or role.
Scenario 3: Diagnosing a 401 response
Use this decision tree:
- No authorization header or malformed value? Check the client, proxy, gateway, and cookie-to-header logic. Confirm the expected format, such as
Bearer <token>. - Token cannot be parsed? Check for truncation, extra quotation marks, URL decoding, line breaks, or accidental inclusion of the word
Bearerinside the token variable. - Signature fails? Check the selected issuer, key set, key identifier, algorithm allow-list, and whether the verifier has refreshed its key cache.
- Signature succeeds but claims fail? Compare
iss,aud,exp,nbf, and required scopes or roles with the API's policy. - Claims pass but access is still denied? Inspect route-level authorization, tenant or resource permissions, gateway policy, and service-to-service identity assumptions.
Scenario 4: Reproducing expiration and clock problems
- Create a short-lived test token through the identity system or a controlled test fixture rather than editing a production token.
- Test a token before its
nbftime, after itsexptime, and near the boundary if your test environment permits it. - Compare the clocks of the client, API, gateway, and identity service. Use a narrowly defined clock-skew allowance where the library and security policy support one.
- Confirm that all components interpret numeric date claims consistently and that milliseconds have not been supplied where seconds are expected.
- Verify that an expired access token follows the intended refresh or reauthentication path without creating an endless retry loop.
What to double-check
JWT claims validation checklist
- Issuer (
iss): Is it the exact trusted issuer configured for this environment? Watch for differences in scheme, hostname, path, or trailing slash. - Audience (
aud): Does the token target this API rather than a web client, another service, or a different environment? Support for a single value or an array should follow the library's documented behavior. - Expiration (
exp): Is the current time before expiration? Confirm units, timezone handling, and the chosen clock-skew policy. - Not before (
nbf): Is the token being used before its allowed start time? - Issued at (
iat): Is it plausible for the environment and useful for detecting an unexpectedly old or future-dated token? - Subject (
sub): Does it identify the expected user or workload, and is it interpreted consistently across services? - Algorithm: Is the algorithm explicitly allow-listed, and does it match the key type and identity-provider configuration?
- Key identifier (
kid): If present, does it select a currently trusted key? Never trust an arbitrary key supplied by the token without controlled key discovery. - Scopes and roles: Are claim names, prefixes, arrays, and case sensitivity consistent with the authorization middleware?
- Environment: Are development, staging, and production issuers, audiences, client IDs, and keys kept distinct?
When an identity provider rotates keys, a verifier should be able to discover the new public key while retaining the old key long enough to validate tokens that are still legitimately in circulation. Check cache duration, refresh-on-unknown-key behavior, failure handling, and monitoring. Do not solve a key mismatch by disabling signature validation.
Safe key-replacement workflow
- Confirm whether the event is planned rotation, an unavailable key, a misconfiguration, or suspected compromise.
- Notify the owners of affected APIs and identity integrations, and preserve relevant security logs without copying live tokens.
- For routine rotation, publish or configure the replacement public key through the supported identity-provider mechanism before issuing tokens that require it.
- Update verifiers, test old and new tokens, and observe validation failures before retiring the old key.
- If compromise is suspected, follow the identity provider's emergency revocation and rotation process, invalidate affected sessions or refresh credentials as appropriate, and review dependent services.
- Store secrets and private signing material in an approved secrets-management system, not source control, container images, or ordinary configuration files. The enterprise secrets management runbook provides related rotation and integration considerations.
Common mistakes
- Confusing decoding with verification: Readable claims are not proof of trust.
- Logging complete tokens: Authorization headers and refresh tokens can function as credentials. Redact them at collection, storage, and display points.
- Accepting any algorithm: A verifier should enforce its configured algorithms and key types rather than adapting to attacker-controlled metadata.
- Checking claims before authenticity: Claims can be changed without a valid signature. Follow the library's secure verification flow.
- Using the wrong audience: A token issued for a frontend or another API may be valid but unusable for the current resource server.
- Ignoring proxy behavior: Gateways and ingress layers can remove, rewrite, or reject authorization headers before the application receives them.
- Retrying every 401 automatically: A retry loop can amplify an outage. Refresh only when the failure indicates an expired access token and cap retries.
- Disabling validation to restore traffic: This converts an integration problem into an authentication risk. Fix issuer, key, audience, or clock configuration instead.
Keep authentication failures distinguishable in internal diagnostics while returning appropriately limited information to external callers. A useful log records the request correlation ID, service, environment, failure category, issuer or key identifier where safe, and time comparison result—not the raw token.
When to revisit
Review this checklist before integrating a new identity provider, adding an API gateway, changing token libraries, or releasing a service that consumes access tokens. Revisit it after a 401 incident, a signing-key rotation, an issuer or audience change, a migration between environments, or a change to scopes, roles, tenant rules, or clock infrastructure.
As a maintenance habit, schedule a review before major seasonal planning or release cycles and whenever authentication workflows or developer tools change. Recheck library examples, supported signing algorithms, provider claim conventions, key-discovery behavior, decoder warnings, and test fixtures after significant identity-platform or authentication-library releases. Record the date, verifier version, identity-provider configuration, and test results so the next investigation starts with known assumptions.
For the next debugging session, use this order: protect the token, capture the request shape, decode without trusting, verify the signature, validate issuer and audience, check time claims and clock skew, inspect authorization policy, and then test the corrected configuration with a non-production token. Pair the result with related operational controls, such as IAM permission troubleshooting and Kubernetes configuration management, so authentication and downstream permissions are diagnosed as separate layers.