A JSON Web Token (JWT) looks like an opaque blob, but it is just three Base64URL-encoded pieces joined by dots. Anyone who holds the token can read what's inside; no secret key is needed. That is by design: JWTs are meant to be signed, not hidden. It is also exactly why you should care where you decode one.
The three parts of a JWT
header eyJhbGciOiJIUzI1NiJ9
payload eyJzdWIiOiIxMjMiLCJleHAiOjE3MDAwMDAwMDB9
signature <binary signature, Base64URL-encoded>
Joined with dots: header.payload.signature
Decoding the first two segments (Base64URL, then JSON) gives you this:
// header
{ "alg": "HS256" }
// payload
{ "sub": "123", "exp": 1700000000 }
- Header: metadata about the token, mainly the signing algorithm (alg) and sometimes the token type (typ) or a key ID (kid).
- Payload: the claims. Registered claims include iss (issuer), sub (subject), aud (audience), exp (expiry), nbf (not before), and iat (issued at). Apps add their own, like roles or a user ID.
- Signature: a cryptographic signature over the header and payload. It proves the token wasn't altered and was issued by someone holding the key.
How to decode one by hand
- Split the token on the two dots to get three segments.
- Take the first segment, swap - for + and _ for /, add = padding until the length is a multiple of 4, and Base64-decode it.
- Parse the result as JSON. That is your header.
- Repeat for the second segment to read the payload.
- Leave the signature alone; it is binary data, not JSON.
In a browser console that is one line: JSON.parse(atob(token.split('.')[1].replace(/-/g, '+').replace(/_/g, '/'))). Note that atob can mangle non-ASCII characters, which is one reason a purpose-built decoder is less error-prone.
Decoding is not verifying
The most common JWT mistake
A token that decodes into a perfectly sensible payload has not been checked at all. Anyone can craft a token with any claims they like; only signature verification tells you whether to trust it.
Verification happens on your server with the right key. It should also check that exp is in the future, that iss and aud match what you expect, and that the alg is one you allow. Never trust the alg header blindly: rejecting the none algorithm and pinning the expected algorithm closes a well-known class of attacks.
Why you shouldn't paste live tokens into random sites
An access token is a credential. Until it expires, whoever holds it can usually act as that user. Many online decoders send whatever you paste to their backend, or load third-party scripts that could log it. Even if the site is honest, you have copied a secret into a place you don't control.
- Prefer a decoder that runs entirely in your browser.
- Open your browser's Network tab while you decode; nothing should be sent.
- Use tokens from a test environment whenever possible.
- If you have pasted a production token somewhere you don't trust, revoke or rotate it.
A quick JWT debugging checklist
- Getting 401 errors? Compare exp with the current time; expired tokens are the number one cause. Remember exp is in seconds, not milliseconds.
- Token rejected as "not yet valid"? Check nbf and iat against clock skew between servers.
- Wrong audience or issuer? Read aud and iss in the payload and compare them with your server's configuration.
- Unexpected permissions? Look at role, scope, or permission claims; they may differ from what you assumed.
- Never store secrets, passwords, or personal data in the payload; it is readable by everyone who sees the token.
Frequently asked questions
Can anyone read the contents of a JWT?
Yes. A standard signed JWT (JWS) is only encoded, not encrypted, so anyone with the token can decode the header and payload. Only the signature protects integrity. If you need the contents hidden, use an encrypted JWT (JWE) or keep sensitive data out of the token.
Is it safe to decode a JWT online?
Only if the decoder runs entirely in your browser and you can confirm nothing is uploaded. Treat any production token you paste into an untrusted site as exposed and rotate it.
What is the difference between decoding and verifying a JWT?
Decoding reads the header and payload. Verifying checks the signature with the correct key and validates claims like exp, iss, and aud. Only verification proves the token is genuine.
Why does my JWT say it is expired?
The exp claim is a Unix timestamp in seconds. If the current time is past that value, the token has expired. Check server clock drift if it expires too early.
Try it: JWT Decoder — free, runs in your browser, nothing is uploaded.
Originally published at ilovekit.app.
