A JSON Web Token often looks like random text, yet a common signed JWT is designed to be readable. Its header and payload are Base64URL-encoded JSON, not encrypted by default. Decoding those two sections can help diagnose an issuer, audience, scope, or expiration problem. It cannot prove that the token is authentic. That distinction is the foundation of safe JWT debugging.
This guide focuses on compact JWTs with three dot-separated sections, the form commonly used for signed access and identity tokens. It explains what a decoder reveals, what registered claims mean, and which checks must still happen in a trusted verification library.
Recognize the three JWT sections
A typical signed JWT has the form header.payload.signature. The header identifies token metadata such as the signing algorithm and sometimes a key identifier. The payload contains claims: name-and-value statements about a subject, issuer, audience, timing, permissions, or application-specific data. The signature protects the encoded header and payload from undetected modification.
The JWT standard, RFC 7519, also allows encrypted and nested forms, so not every token can be understood by simply splitting it into three pieces. If a compact token has five sections, it is likely a JWE and requires the appropriate decryption key and library rather than an ordinary decoder.
Decode Base64URL correctly
Base64URL is a URL-safe variant of Base64. It substitutes - and _ for characters that are awkward in URLs and commonly omits = padding. A decoder must restore or tolerate the missing padding and decode UTF-8 JSON. Treating a segment as standard Base64 without those adjustments is a common reason a valid token appears malformed.
After decoding, parse both sections as JSON. A header might contain {"alg":"RS256","typ":"JWT","kid":"key-7"}, while a payload might contain iss, sub, aud, exp, and custom claims. Formatting the JSON makes the contents easier to scan, but it does not involve the signature or a secret key.
Read registered claims in context
The iss claim names the issuer, sub identifies the subject in the issuer's context, and aud identifies the intended recipient or recipients. exp is the expiration time, nbf says the token must not be accepted before a time, and iat records when it was issued. jti provides a token identifier that can support replay controls or revocation strategies.
These names do not validate themselves. A token for another API can be perfectly signed and unexpired yet still be invalid for your service because its audience is wrong. A subject identifier is not necessarily an email address or globally unique account. Interpret every claim according to the issuer's documented contract, and avoid granting access from an unfamiliar custom field merely because it exists.
Convert JWT timestamps without guessing
JWT numeric dates count whole or fractional seconds from the Unix epoch. JavaScript Date values use milliseconds, so multiply a claim by 1,000 before constructing a date. A value such as 1710000000 is plausible in seconds; interpreting it as milliseconds produces a date close to January 1970. Conversely, treating a 13-digit millisecond value as seconds produces a date far in the future.
Display the result in UTC first so the instant is unambiguous, then optionally show local time for the reader. Verification code may allow a small clock-skew tolerance for distributed systems, but that allowance should be explicit and limited. Decoding an expiration date in a browser is useful for diagnosis; the server must still enforce it.
Decoding is not signature verification
Anyone can create new Base64URL text and replace the payload. A decoder will display the modified claims as readily as legitimate ones. Verification uses the exact encoded header and payload, the signature, an approved algorithm, and a trusted key associated with the expected issuer. If any part has changed, correct verification fails.
Never accept the token's algorithm as an unchecked instruction. Configure the algorithms your application permits, obtain keys through a trusted path, handle key rotation deliberately, and validate issuer and audience after the cryptographic check. Mature JWT libraries implement these rules more safely than handwritten verification code.
Do not paste live bearer tokens into unknown sites
An access token may be a bearer credential: whoever possesses it can use it until it expires or is revoked. The readable payload can also contain internal identifiers, tenant names, roles, or personal data. Before debugging, prefer a local browser decoder that does not transmit the token, or create a synthetic token in a non-production environment.
If a real token was shared with an untrusted service, copied into a public issue, or committed to a repository, treat it as exposed. Revoke it when possible, rotate related credentials if necessary, and remove it from logs and history. Redacting only the signature is not a general safety guarantee because the payload itself may be sensitive.
A complete JWT validation checklist
Production acceptance normally requires more than checking exp. Verify the signature with an explicitly permitted algorithm and trusted key. Require the expected issuer and audience. Enforce expiration and not-before timing with a controlled clock tolerance. Confirm that token type, scopes, roles, nonce, or other application claims match the current operation. Apply revocation or replay controls where the threat model requires them.
Also distinguish access tokens from ID tokens. A token minted to tell a client who signed in is not automatically valid authorization for an API. Token profiles add rules beyond the base JWT format, so follow the identity provider's documentation and the relevant OAuth or OpenID Connect validation requirements.
Use a decoder as an inspection tool
A JWT decoder is excellent for answering focused questions: Which issuer produced this token? Is the audience correct? When does it expire? Which key identifier does it request? Does the payload contain the scope the client expected? It is not an authentication decision engine.
The safe mental model is “decode to inspect, verify to trust.” Keep production tokens private, translate numeric dates carefully, and let a maintained library perform cryptographic and claim validation on the server. With those boundaries, decoding becomes a fast debugging technique without turning readable claims into assumed facts.