A JWT decoder can quickly reveal whether a token contains the claims your application expects, but decoding is not the same as validating. This guide provides a reusable workflow for inspecting JWT headers and payloads locally, verifying signatures and registered claims, diagnosing algorithm or environment mismatches, and debugging authentication without sending live production tokens to an untrusted tool.
Overview
A JSON Web Token, or JWT, is usually represented as three Base64URL-encoded parts separated by periods:
header.payload.signature
The header describes how the token is signed. The payload contains claims, which are statements about the subject, authorization context, or token lifetime. The signature allows a verifier with the appropriate key to detect whether the signed content has been altered.
A browser-based JWT decoder can make the first two parts readable, but it generally cannot prove that a token is authentic. Anyone can create a string that looks like a JWT, and the header and payload are not encrypted merely because they are encoded. Treat every decoded claim as untrusted until signature verification and application-specific checks succeed.
For safe debugging, start with a non-sensitive test token or inspect the token locally. If a production token must be examined during an incident, avoid pasting it into websites, chat rooms, tickets, screenshots, shell history, or logs. A bearer token may be usable by anyone who obtains it until it expires or is revoked according to the issuing system's design.
JWT claims explained
| Claim or field | Purpose | What to check |
|---|---|---|
alg | Identifies the signing algorithm used by the token. | It must match an explicitly allowed algorithm in the verifier. Do not accept an algorithm merely because the token requests it. |
kid | Identifies a signing key, often during key rotation. | Confirm that it maps to an expected key. Treat key-selection input carefully and do not construct arbitrary key URLs from it. |
iss | Identifies the issuer. | Compare it with the exact issuer configured for the environment. |
sub | Identifies the token subject. | Confirm that the subject format and identity are valid for the application. |
aud | Identifies the intended audience. | Check the expected audience, including whether the value is a string or an array. |
exp | Expiration time, normally represented as a NumericDate. | Reject expired tokens, allowing only a deliberately configured clock tolerance. |
nbf | Not-before time. | Reject tokens used before their valid start time, subject to documented clock tolerance. |
iat | Issued-at time. | Use it for diagnostics and, where appropriate, enforce an acceptable token age. |
jti | Token identifier. | Use it for tracing or replay controls when the authentication design supports that. |
Custom claims are application-specific. Document their expected type, meaning, and trust requirements rather than assuming that a claim such as role, scope, or email is safe to use before validation.
Checklist by scenario
Scenario 1: You need to decode a JWT token for inspection
- Confirm that the token is suitable for inspection. Prefer a locally generated development token with synthetic identities and permissions.
- Copy the token without changing whitespace or characters. A JWT is sensitive to accidental edits, even though the header and payload may still appear readable afterward.
- Split it into exactly three period-separated segments. An encrypted JWT or a malformed value may not have the same readable structure.
- Decode the header and payload as Base64URL, then parse each as JSON.
- Record the token source, environment, timestamp, and request context separately from the token itself.
- Redact the signature and sensitive claim values before adding diagnostic output to a ticket or incident channel.
For local inspection, use a short script or a trusted command-line utility that does not transmit input to a remote service. A decoder is an inspection aid, not a security decision-maker.
Scenario 2: An API returns an authentication or authorization error
- Compare the token's
issandaudvalues with the API's configured issuer and audience for the same environment. - Convert
exp,nbf, andiatinto readable timestamps and compare them with the server clock, not only your laptop clock. - Check whether the client sent the complete token in the expected
Authorization: Bearerformat. - Confirm that the token was issued for the requested API, rather than for a user interface, identity service, or different environment.
- Inspect scopes, roles, or permissions only after signature validation. A readable permission claim is not proof that the caller has that permission.
- Compare the failing token with a known-good test token while keeping both values private.
Scenario 3: Signature validation fails
- Identify the algorithm in the header and compare it with the verifier's allowlist.
- Determine whether the verifier expects a shared secret, a public key, or a key selected from a trusted key set.
- Check the key identifier, key rotation state, and environment. A development token may be signed by a different issuer or key set than production.
- Confirm that the complete original token is being verified. Re-serializing the header or payload can change the signed bytes.
- Check whether the library expects a particular key format, such as a PEM-encoded public key or a correctly configured JWK.
- Review the verifier's clock tolerance and claim-validation settings rather than weakening them to make one token pass.
Scenario 4: You are investigating a suspected token exposure
- Stop sharing the token and remove it from places where it was accidentally posted, recognizing that removal may not erase copies or logs.
- Determine the issuer, subject, audience, expiration, and likely permissions without distributing the raw value.
- Follow the identity provider or application process for revocation, key rotation, session invalidation, or credential replacement.
- Search access logs using safe identifiers such as request IDs, subject identifiers, or token fingerprints when available.
- Record what was exposed, where it appeared, who could access it, and what containment action was taken.
- After containment, update debugging practices so future diagnostics use synthetic tokens and redacted logs.
What to double-check
Decoding versus validation
Decoding answers, “What JSON is represented by these first two segments?” Validation answers, “Was this token signed by a trusted issuer, has it been altered, is it intended for this service, and is it currently valid?” Keep these operations separate in code and in incident notes.
Algorithm and key handling
Configure the verifier with an explicit list of accepted algorithms and the expected key material. Do not let an untrusted token choose an algorithm or cause the application to fetch a key from an arbitrary location. Use the verification behavior recommended by the maintained version of the JWT library used by your service, and test rejected as well as accepted tokens.
Issuer, audience, and environment
A valid signature alone does not necessarily mean that a token belongs to your application. Check the exact issuer and intended audience. Keep development, staging, and production configuration distinct, including issuer URLs, audience values, key sets, and client identifiers.
Time and data types
JWT time claims are commonly NumericDate values rather than formatted date strings. Check units, clock synchronization, and the library's handling of missing or malformed values. Also verify whether claims such as aud and scope arrive as strings, arrays, or another documented type.
Logging and privacy
Do not log complete bearer tokens by default. Redact authorization headers and token values in application, proxy, CI/CD, and observability systems. If correlation is necessary, use a carefully designed fingerprint or request identifier rather than the credential itself.
Common mistakes
- Assuming Base64URL is encryption. Anyone who receives a JWT may be able to read its header and payload. Never put secrets in claims unless the token design explicitly provides confidentiality through encryption.
- Trusting a decoded role or scope. Claims become trustworthy only after the signature, issuer, audience, time, and application authorization rules have been checked.
- Using a public decoder with a live token. A convenient JWT decoder may transmit or retain submitted data. Use local tooling for sensitive values.
- Accepting whatever algorithm appears in the header. The verifier should enforce its own algorithm policy and key type.
- Checking expiration but not audience. An unexpired token issued for another service can still be inappropriate for the current API.
- Disabling verification to isolate a bug. If inspection is needed, decode a copy locally or use a safe test fixture. Do not make an authentication path accept unverified claims, even temporarily, without strict isolation.
- Forgetting rotation and caching behavior. A newly rotated signing key may not be available to every verifier immediately. Diagnose key-set refresh behavior without turning off signature checks.
When reporting a JWT issue, use this compact worksheet: environment; issuer; audience; algorithm; key identifier; token issued, not-before, and expiration times; expected versus observed status; library and version; verification error category; and whether the token was synthetic or production-derived. Leave out the raw token.
When to revisit
Revisit this checklist whenever authentication configuration, identity providers, JWT libraries, signing algorithms, key-rotation procedures, or API audiences change. It is also useful before seasonal planning cycles, major releases, new environment launches, and incident-response exercises. Review the security cautions at least every six months, even if the implementation appears unchanged.
Before closing a debugging task, run this practical sequence:
- Reproduce the issue with a synthetic token whenever possible.
- Decode locally and capture only the claims needed for diagnosis.
- Validate the signature with an explicitly configured algorithm and trusted key.
- Check issuer, audience, expiration, not-before time, and application permissions.
- Remove raw tokens from commands, logs, tickets, screenshots, and chat.
- Document the library configuration and environment-specific differences.
- Test both the expected success path and deliberately invalid tokens.
A safe JWT debugging workflow makes the decoder a narrow developer tool: useful for understanding token structure, never a substitute for cryptographic verification or authorization policy.