A JWT decoder is useful for troubleshooting authentication, but decoding is not verification. This guide provides a reusable checklist for inspecting a token’s structure, claims, timestamps, and algorithm, then explains how to validate it safely without exposing production credentials or trusting unverified data.
Overview
JSON Web Tokens, commonly called JWTs, are compact strings used to carry claims between parties. A typical signed JWT has three dot-separated parts:
- Header: JSON metadata describing the token type and signing algorithm.
- Payload: JSON claims such as the subject, issuer, audience, and expiration time.
- Signature: A value used by a verifier to detect whether the header and payload were altered.
The header and payload are encoded with base64url, not encrypted. Anyone who has the token can usually decode those sections. A JWT token decoder online or a local JavaScript utility can therefore help you inspect a token, but the displayed claims are only input data until a trusted verifier checks the signature and validation rules.
Keep that distinction at the center of every investigation: decoded does not mean authentic, current, authorized, or safe to display. Treat an unfamiliar token as sensitive. Even when its payload is readable, it may contain identifiers, scopes, email addresses, or other information that should not be pasted into an external website.
For related data work, a local JSON formatter and validation workflow can make claims easier to inspect without sending them to a third-party service.
JWT fields at a glance
| Field | Purpose | Inspection question |
|---|---|---|
alg | Identifies the signing algorithm. | Does the server allow this algorithm explicitly? |
typ | Often indicates the token type, such as JWT. | Does the application expect this token type? |
iss | Identifies the intended issuer. | Does it match the configured identity provider? |
aud | Identifies the intended recipient or service. | Does it match this API’s configured audience? |
sub | Identifies the subject, often a user or service. | Is this identity interpreted consistently? |
exp | Expiration time expressed as a NumericDate. | Has the token expired according to the verifier’s clock? |
nbf | Earliest time at which the token should be accepted. | Is the token being used too early? |
iat | Time at which the token was issued. | Is its age plausible for this flow? |
jti | Token identifier, when present. | Is it needed for replay tracking or revocation? |
Checklist by scenario
When you need to inspect a token
- Work with a non-production sample. Prefer a redacted, expired, or locally generated token. Do not paste live access or refresh tokens into an online decoder unless your organization has approved that workflow and the tool’s handling is understood.
- Count the segments. A signed compact JWT normally contains three non-empty, dot-separated segments. An encrypted JWT uses a different five-part compact structure, so do not assume every token can be interpreted as an ordinary signed JWT.
- Decode only the first two segments. Convert base64url to bytes, decode as UTF-8, and parse the result as JSON. A decoding error may indicate truncation, whitespace, an incorrect token type, or an encoding problem.
- Record the header and claims separately. Save the original token only where your security process allows it, and avoid logging it in browser consoles, CI output, issue trackers, or chat.
- Read claims as untrusted input. A payload saying
"role":"admin"does not grant administrative authority. Only the server-side authorization path should make that decision after successful verification.
When an API request is rejected
- Check whether the token was sent in the expected
Authorization: Bearerformat, without accidental quotation marks or line breaks. - Compare
expandnbfwith the verifier’s current time. JWT NumericDate values are measured in seconds, while JavaScript’sDate.now()returns milliseconds. - Compare
issandaudwith the API’s configuration, including exact spelling and expected array-versus-string handling foraud. - Check whether the signing key is available and whether the token’s key identifier, such as
kid, maps to an expected key. - Review server-side validation logs without recording the complete token. A reason such as “expired,” “issuer mismatch,” or “signature invalid” is more useful and safer than dumping credentials.
When you are implementing validation in JavaScript
Use a maintained JWT library or the authentication platform’s supported verifier rather than writing signature validation from scratch. Configure an explicit allowlist of algorithms and expected issuer and audience values. The verifier should reject malformed tokens, unexpected algorithms, invalid signatures, unacceptable timestamps, and claims that do not meet the application’s policy.
Keep verification on a trusted server or service boundary when the result controls API access. Browser code may decode a token for a user interface hint, but it must not use decoded claims as proof of identity or permission. A simple inspection helper can illustrate the distinction:
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));
}
const [encodedHeader, encodedPayload] = token.split('.');
const header = decodeJwtPart(encodedHeader);
const payload = decodeJwtPart(encodedPayload);
// Inspection only: no signature or claim validation has occurred.
This example is deliberately incomplete as a validator. It does not verify a signature, enforce an algorithm policy, validate issuer or audience, check time claims, or protect against every malformed input. Use it only to understand decoding and keep real authorization decisions inside a proper verification flow.
What to double-check
Algorithm and key handling
Do not accept whatever algorithm the token announces. The server should select permitted algorithms through configuration and use the correct key type. Symmetric algorithms use a shared secret; asymmetric algorithms use a private signing key and a public verification key. Confusing those models, accepting an unexpected algorithm, or automatically trusting a key reference supplied by an attacker can undermine validation.
The kid header can help select a configured public key, but it should not become an unrestricted file path, URL, or database query. Key rotation also deserves an explicit plan: retain appropriate verification keys long enough to process valid tokens, publish or configure trusted public keys safely, and remove old keys according to the application’s rotation policy.
Time claims and clock tolerance
Check exp, nbf, and sometimes iat using seconds, not milliseconds. Small clock differences can affect boundary cases, so a verifier may use a narrowly defined clock tolerance. That tolerance should be intentional and documented; it should not turn an expired token into a long-lived credential.
Authentication versus authorization
A valid signature shows that the token was signed by a trusted issuer and that its signed contents have not changed. It does not automatically prove that the current request should perform a particular action. After verification, enforce authorization separately: check the subject, scopes, roles, tenant boundaries, resource ownership, and any application-specific rules.
For broader review, the JavaScript code review checklist can help connect token handling with logging, error management, and maintainability checks.
Common mistakes
- Calling base64url decoding validation. Anyone can decode a JWT payload. Validation requires signature verification and policy checks.
- Trusting client-side role checks. Hiding a button in the browser is a usability choice, not an access-control boundary.
- Logging complete tokens. Access tokens in logs can be replayed. Log a request identifier and a safe failure category instead.
- Using a production token in an online tool. Prefer local tooling, redacted samples, or an approved internal utility.
- Ignoring audience and issuer. A correctly signed token intended for another service may still be unacceptable to the current API.
- Assuming expiration is revocation. A token can remain valid until its expiration unless the system has a separate revocation, rotation, or session-control mechanism.
- Printing secrets during debugging. Use masked values and remove temporary diagnostics before merging or deploying.
If token failures appear alongside parsing, pattern, or input-cleaning problems, keep those concerns separate. A JavaScript regex testing guide may help investigate input patterns, but regular expressions are not a substitute for JWT verification.
When to revisit
Return to this checklist whenever an authentication flow changes, a token issuer or library is upgraded, signing keys rotate, a new API audience is introduced, or an incident prompts a review of token handling. Recheck the verifier’s algorithm allowlist, issuer and audience configuration, time handling, key discovery, error logging, and authorization rules.
It is also worth revisiting before a major release or seasonal planning cycle when teams review dependencies, environments, and operational workflows. Confirm that development, staging, and production use the intended keys and issuers; test expired, malformed, wrong-audience, wrong-issuer, and invalid-signature cases; and verify that sensitive values are absent from logs and support artifacts.
Practical final check: decode only to understand a token, verify only with trusted server-side code, authorize only after verification, and treat every token as sensitive until it has been safely retired.