A rejected JWT can fail because it is expired, intended for a different service, signed with an unavailable key, or merely decoded without being verified. This guide provides a repeatable workflow for safely inspecting a token, validating its claims and signature, diagnosing common 401 responses, and deciding when your JWT debugging process needs review.
Overview
A JSON Web Token (JWT) is a compact token commonly used to carry authentication or authorization data between systems. A typical JWT has three Base64URL-encoded parts separated by periods:
header.payload.signature
The header describes the token type and signing algorithm. The payload contains claims such as an issuer, subject, audience, issued-at time, and expiration time. The signature helps a verifier detect whether the signed content was altered and whether it was produced with a trusted key.
These parts are encoded, not encrypted, by default. Anyone who obtains a JWT can usually decode the header and payload, so tokens should not contain passwords, private keys, API secrets, or other confidential data. A JWT decoder is useful for inspection, but decoding alone does not establish that a token is authentic or safe to accept.
Use this sequence when an API rejects a token:
- Capture the exact token and the complete HTTP response without sharing it publicly.
- Decode the header and payload locally or with an approved tool.
- Check time-based claims and the expected issuer and audience.
- Confirm that the algorithm and key match the verifier configuration.
- Perform signature verification on the server or in a controlled test environment.
- Compare the result with the API's authorization rules and request context.
For broader HTTP diagnosis, pair this workflow with the HTTP status codes reference and the API debugging runbook.
What to track
Header values
Start with the header, especially alg and kid. The alg value identifies the signing algorithm expected by the token. The optional kid value identifies a key, which is important when a service publishes several active or recently rotated keys.
Do not let an incoming token choose an algorithm that your application did not explicitly permit. Configure an allowlist appropriate for the service and reject unexpected algorithms before accepting claims. Never treat a missing or unfamiliar kid as a reason to bypass signature verification.
Claims and validation inputs
Record the claims that your API actually requires, along with the expected values:
exp: the expiration time. A token past this time should normally be rejected.nbf: the not-before time. A token may be invalid if used before this time.iat: the issued-at time. It can help identify stale, future-dated, or unexpectedly long-lived tokens.iss: the issuer. Compare it with the exact issuer configured for the API.aud: the intended audience. A token issued for one API should not automatically be accepted by another.sub: the subject or principal. Check that it maps to a valid user or service identity.- Scopes, roles, or permissions: these affect authorization after authentication succeeds.
Keep a small diagnostic record for each environment: expected issuer, audience, accepted algorithms, key source, clock assumptions, and the claim used for authorization. Redact token values and personal data. A hash or short fingerprint can help correlate repeated requests without storing the token itself.
Decoding versus verification
A local decoder can reveal malformed JSON, an unexpected audience, or an expired timestamp. It cannot prove that the token came from the expected issuer. Verification requires the correct cryptographic key and checks the signature against the exact encoded header and payload.
Browser-based tools are convenient for throwaway test tokens, but pasting production tokens into an online JWT decoder creates an avoidable disclosure risk. Prefer a local utility, a controlled development tool, or a redacted sample. Treat every real access token as a credential, even when its payload looks harmless.
Algorithm and tool choices
| Area | What to check | Security limitation |
|---|---|---|
| Symmetric signing | A shared secret is available to both signer and verifier. | Every system holding the secret may be able to sign tokens, so key distribution and storage require care. |
| Asymmetric signing | The verifier has the correct public key and the signer protects the private key. | Key selection, rotation, and retrieval failures can reject otherwise valid tokens. |
| JWT decoder | Header and claims can be inspected for structure and expected values. | Decoding is not signature verification and does not establish trust. |
| Validation library | Algorithm, issuer, audience, time claims, and key checks are configured explicitly. | Defaults and APIs differ; review the library's current documentation before upgrading or changing configuration. |
| Browser-based tool | Useful only with synthetic or deliberately redacted tokens. | Do not expose production tokens, secrets, or personal data to an unapproved service. |
Cadence and checkpoints
JWT failures are often intermittent because authentication depends on clocks, key sets, identity-provider settings, deployment versions, and environment-specific configuration. Add JWT checks to a recurring review rather than investigating only after users report failed sessions.
For every deployment
- Run a valid-token test against the intended issuer and audience.
- Run negative tests for an expired token, wrong audience, wrong issuer, altered payload, unsupported algorithm, and missing required claim.
- Confirm that logs identify the validation stage without recording the full token.
- Check that the API returns a useful authentication error while avoiding sensitive diagnostic details in client responses.
Monthly or quarterly
Review accepted algorithms, key identifiers, key rotation procedures, clock synchronization, token lifetimes, and dependency versions. Confirm that old keys are retired according to a deliberate process rather than disappearing unexpectedly. If your system consumes a remote key set, test behavior when a key is temporarily unavailable and when a new key appears.
Also inspect the most common validation failures by environment. A concentration of expired tokens suggests refresh or session-lifetime problems; a concentration of audience failures suggests configuration drift; a sudden increase in unknown-key errors may point to rotation timing or key-cache behavior.
When an API contract changes, include JWT expectations in the same review as request and response changes. The OpenAPI contract testing guide can help organize those checks.
How to interpret changes
Expired or not-yet-valid tokens
Compare exp, nbf, and iat with the verifier's current time. Check the time zone representation and whether infrastructure clocks are synchronized. A small, explicitly configured clock tolerance can address ordinary clock skew, but it should not become a substitute for fixing incorrect system time or accepting very old tokens.
Issuer and audience failures
Compare values exactly, including scheme, host, path, and trailing slash behavior where applicable. Development, staging, and production identity providers may issue tokens with different values. Verify that the client is requesting a token for the API it is calling, rather than reusing a token intended for another resource.
Signature and key errors
A signature failure can mean the token was changed, the wrong secret or public key was selected, the algorithm is not allowed, or the key set is stale. Compare the token's kid with the keys available to the verifier. During rotation, ensure the verifier can obtain the new public key before tokens signed with it are issued, while retaining old verification keys for tokens that have not yet expired.
Authentication versus authorization
If signature and registered claims pass but the request still fails, inspect authorization. The subject may lack a required role or scope, the route may require a different permission, or the application may be reading a claim under the wrong name. Separate these failures in logs and tests so that a permission problem is not misdiagnosed as a JWT parsing problem.
A small local inspection example
The following JavaScript function is suitable for inspecting a non-sensitive development token. It intentionally does not verify a signature and should not be used to authorize a request:
function decodeJwtPart(part) {
const base64 = part.replace(/-/g, "+").replace(/_/g, "/");
const padded = base64.padEnd(Math.ceil(base64.length / 4) * 4, "=");
return JSON.parse(atob(padded));
}
function inspectJwt(token) {
const parts = token.split(".");
if (parts.length !== 3) throw new Error("Expected three JWT parts");
return {
header: decodeJwtPart(parts[0]),
payload: decodeJwtPart(parts[1])
};
}
For production validation, use a maintained server-side JOSE or JWT library and configure its allowed algorithms, trusted key source, issuer, audience, and time checks explicitly. Keep verification in the trust boundary; never accept a decoded payload from a browser as proof of identity.
When to revisit
Revisit this guide and your implementation on a monthly or quarterly cadence, and immediately after a significant authentication change. The most important triggers are a library upgrade, a new identity provider, a signing-algorithm change, key rotation, altered token lifetimes, a new API audience, or a security disclosure affecting a dependency or JOSE-related component.
Use this practical checklist:
- Store the current validation assumptions: issuer, audience, algorithms, key source, claim requirements, and clock tolerance.
- Test one known-good token and each important failure mode in every environment.
- Review logs for trends without logging bearer tokens or secrets.
- Confirm that rotation and rollback procedures work before an incident occurs.
- Update examples and library configuration when APIs or security guidance change.
- Document the date, reviewer, environments tested, and unresolved findings.
A dependable JWT debugging process is not just a way to decode a token. It is a repeatable set of checks that distinguishes malformed data, expired claims, configuration drift, key-management failures, and authorization decisions. Keep those checkpoints current, and a difficult 401 response becomes a bounded investigation rather than a guess.