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

ClaimNameWhat to check
issIssuerEquals the auth server you trust.
subSubjectThe user or client the token is about.
audAudienceIncludes your API. A token minted for another service must be rejected.
expExpiration timeNow is before it (allow a small clock skew, such as 30–60 seconds).
nbfNot beforeNow is after it.
iatIssued atUseful for logging and for rejecting very old tokens.
jtiJWT IDA 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 kid says which key to use.

Mistakes that become security bugs

  1. 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.
  2. 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.
  3. Skipping exp and aud. A valid signature only proves who issued the token, not that it's still valid or meant for you.
  4. 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.
  5. 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

References