JWT Explained: How to Decode, Verify and Debug JSON Web Tokens

What is inside a JWT, the difference between decoding and verifying, how expiry and clock skew work, and the security mistakes that cause real breaches.

The three parts of a token

A JSON Web Token is three Base64URL-encoded strings joined by dots: header.payload.signature. The header is a small JSON object naming the signing algorithm (for example HS256 or RS256) and often a key ID (kid). The payload holds the claims: who the token is about, who issued it, and when it expires. The signature is computed over the first two parts with a secret or private key.

Base64URL is not encryption. Anyone who has the token can read the header and payload by decoding them, which is exactly what a JWT decoder does. Treat everything in a standard JWT payload as public: never put passwords, API secrets or sensitive personal data in it.

Decoding is not verifying

Decoding shows you what a token claims. Verifying proves the claims were issued by someone who holds the key and have not been altered. A decoder is a debugging tool; it answers questions like "which user is this token for?" or "why is this request being rejected as expired?". It must never be the basis of an authorization decision.

Your server should verify every token on every request with a maintained library, pinning the algorithms it accepts. Accepting whatever algorithm the header names is the root of the classic "alg: none" and RS256-to-HS256 confusion attacks, where an attacker forges a token the server happily accepts.

Registered claims worth knowing

iss (issuer) names who created the token. sub (subject) identifies the user or client. aud (audience) names the service the token is meant for; a token minted for one API should be rejected by another. exp (expiration) and nbf (not before) bound the validity window, and iat (issued at) records creation time.

exp, nbf and iat are NumericDate values: seconds since the Unix epoch, not milliseconds. A common bug is a JavaScript service writing Date.now() (milliseconds) into exp, which produces a token that appears to expire tens of thousands of years from now. If an exp value has 13 digits, that is almost certainly what happened.

Debugging "token expired" errors

When a token is rejected as expired, decode it and compare exp with the current time in UTC. If the token looks valid by a few seconds or minutes, the cause is usually clock skew between the issuing server and the verifying server. Most libraries accept a small leeway (30 to 60 seconds); larger gaps point to a server whose clock is not synced with NTP.

If exp is far in the past, the client is caching a token and not refreshing it. Check that your client reads the refresh token flow correctly and that it refreshes slightly before exp rather than waiting for a 401.

Common mistakes

Storing long-lived JWTs in localStorage exposes them to any script that runs on the page, including injected third-party scripts. Short lifetimes (minutes, not days) plus refresh tokens in httpOnly cookies limit the damage of a leak.

JWTs cannot be revoked by default: a stolen token stays valid until exp. If you need instant logout or account suspension, keep lifetimes short or maintain a deny-list keyed by the token's jti claim.

Finally, be careful where you paste tokens. A production token pasted into an online tool that sends it to a server is a leaked credential. Use a decoder that runs entirely in your browser, or decode locally, and rotate any token you suspect was exposed.

JWT Decoder