Home › Guides › How a JWT Works
How a JWT Works: Decoding a Real Token
A JSON Web Token (JWT) is a compact string that carries a few facts, called claims, plus a signature that proves they haven't been changed. APIs use them to say "this request comes from user 42 and is valid until 1:00". The most important thing to know: a normal JWT is signed, not encrypted. Anyone who has the token can read what's inside. This guide takes a real token apart, explains the claims and algorithms, and lists the mistakes that cause security bugs.
Three parts separated by dots
Here is a complete token (line breaks added at the dots):
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9
.eyJzdWIiOiJ1c2VyXzQyIiwibmFtZSI6IkFkYSBMb3ZlbGFjZSIsInJvbGUiOiJhZG1pbiIsImlhdCI6MTc2NzIyNTYwMCwiZXhwIjoxNzY3MjI5MjAwfQ
.pewMZ6xPU9HryYjHBp6ZPVvJpE1d-syXsamS3fXsXOA
The structure is header.payload.signature. The first two parts are JSON encoded with Base64URL, a variant of Base64 that uses - and _ instead of + and / and drops the = padding, so the token is safe in URLs and headers.
Header
{"alg":"HS256","typ":"JWT"}
alg names the signing algorithm. typ says it's a JWT.
Payload
{"sub":"user_42","name":"Ada Lovelace","role":"admin","iat":1767225600,"exp":1767229200}
The payload holds the claims. iat and exp are Unix timestamps in seconds: 1767225600 is January 1, 2026 at 00:00 UTC, and 1767229200 is one hour later. The Unix timestamp converter turns them into readable dates.
Signature
For HS256 the signature is an HMAC-SHA256 of header.payload (the two encoded parts joined by a dot) using a secret key, then Base64URL-encoded. The token above was signed with the secret demo-secret-do-not-use. Paste the token into TokenSmith with that secret and the signature verifies. Change one character of the payload and it fails. The HMAC generator computes the same HMAC-SHA256 in Base64; swap + for -, / for _ and drop any = to get the Base64URL form in the token.
Decoding a token yourself
Because the payload isn't encrypted, decoding needs no key and no server. In a browser console or Node.js:
const [header, payload] = token.split('.').slice(0, 2).map(part =>
JSON.parse(atob(part.replace(/-/g, '+').replace(/_/g, '/')))
);
(This simple version is fine for ASCII claims; names with accents or emoji need a proper UTF-8 decode, which TokenSmith does.) The same fact is a warning: never put passwords, card numbers or other secrets in a JWT payload. If the contents themselves must be hidden, you need an encrypted token (JWE), not a signed one.
Registered claims
| Claim | Name | What to check |
|---|---|---|
iss | Issuer | Equals the auth server you trust. |
sub | Subject | The user or client the token is about. |
aud | Audience | Includes your API. A token minted for another service must be rejected. |
exp | Expiration time | Now is before it (allow a small clock skew, such as 30–60 seconds). |
nbf | Not before | Now is after it. |
iat | Issued at | Useful for logging and for rejecting very old tokens. |
jti | JWT ID | A unique ID, used if you need to block a single token. |
Anything else (name, role above) is a custom claim. Keep the payload small, since the token is sent with every request.
HS256 vs. RS256 and ES256
- HS256 (HMAC with SHA-256) uses one shared secret to sign and verify. Simple, but every service that verifies tokens can also create them. Use a long random secret, at least 32 bytes; short or guessable secrets can be cracked offline from a single token.
- RS256 (RSA) and ES256 (ECDSA) sign with a private key and verify with a public key. Only the auth server can issue tokens, and any service can verify them. Identity providers usually publish their public keys at a JWKS URL, and the token header's
kidsays which key to use.
Mistakes that become security bugs
- Decoding instead of verifying. Reading the payload without checking the signature means anyone can edit
"role":"admin"into their own token. Always verify with a maintained library. - Trusting the token's
alg. Accepting"alg":"none", or letting an attacker switch RS256 to HS256 and sign with your public key as the "secret", are classic attacks. Configure the allowed algorithm on the server and reject everything else. - Skipping
expandaud. A valid signature only proves who issued the token, not that it's still valid or meant for you. - Long-lived access tokens. A JWT can't easily be revoked before it expires. Keep access tokens short (minutes, not days) and use refresh tokens to get new ones.
- Pasting production tokens into online decoders. A live token is a credential until it expires. Use a decoder that runs locally. TokenSmith runs entirely in your browser, and you can confirm in the Network tab that nothing is sent.
Where to store a JWT in a browser
There is no perfect answer, only trade-offs. localStorage is easy but readable by any script on the page, so a single XSS bug leaks the token. An HttpOnly, Secure, SameSite cookie can't be read by scripts, but cookies are sent automatically, so you need CSRF protection for state-changing requests. Many apps keep the short-lived access token in memory and the refresh token in an HttpOnly cookie.
Related tools
- TokenSmith: decode, verify (HS256/384/512) and generate JWTs locally.
- Base64 Switch: encode and decode Base64 by hand.
- HMAC Generator: compute the HMAC behind an HS256 signature.
- UnixTime: read
exp,iatandnbfas dates.