Guide
How JWT authentication works
A plain-English guide to JSON Web Tokens — how they are structured, signed, and verified — with a decoder built in so you can inspect your own token.
A JSON Web Token (JWT) is a compact, self-contained way to carry claims — usually "who this user is" — between a client and a server. After you log in, the server hands you a token; you send it back on each request, and the server trusts it because it can verify the token was not tampered with. Paste any token into the decoder above to follow along.
The three parts
A JWT is three Base64URL-encoded sections joined by dots: header.payload.signature.
- Header — the token type and the signing algorithm, e.g.
{ "alg": "HS256", "typ": "JWT" }. - Payload — the claims, e.g.
{ "sub": "123", "name": "Ada", "exp": 1735689600 }. - Signature — a cryptographic signature over the header and payload, made with a secret or private key.
The header and payload are encoded, not encrypted. That is the single most important thing to understand: anyone holding the token can decode and read them. The security comes from the signature, not from hiding the contents.
How signing and verification work
When the server issues a token, it computes the signature like this (for HS256):
HMAC-SHA256( base64url(header) + "." + base64url(payload), secret )
On every later request, the server recomputes that signature from the token's header and payload
using its own secret and compares it to the signature in the token. If they match, the token is
authentic and untouched. If even one character of the payload was changed, the signatures differ
and the token is rejected. The decoder above can verify an HS256/384/512 token if you paste the
secret.
Common claims
sub— the subject (typically the user id).iat— issued at, a Unix timestamp.exp— expires at, a Unix timestamp; after this time the token is invalid.iss/aud— the issuer and intended audience.
Keep payloads small and never include passwords, secrets, or anything you would not want the client to read.
Security do's and don'ts
- Do set a short
expand use refresh tokens for long sessions. - Do verify the signature and the
exp,iss, andaudon every request. - Don't accept the
algfrom the token blindly — pin the algorithm server-side to avoid "alg: none" and algorithm-confusion attacks. - Don't store secrets in the payload — it is readable by anyone.
Once you understand the three parts and the signature, JWTs stop being mysterious: they are just signed JSON. Use the decoder above to inspect a real token, check its expiry, and verify its signature.