What a JSON Web Token is: its header, payload and signature, why an edited token gets rejected, and how to verify and store JWTs without the common mistakes.
JWT, explained by cats. Kitty logs into her Tuna App. The server checks her password. All good. Kitty is allowed inside. But Kitty doesn’t want to log in again every time she clicks something. So the server gives Kitty a JWT.
a JSON Web Token. A little signed note that says: ‘This is Kitty. She’s verified.’ Kitty keeps this token. She sends it with every request. The server checks the signature. If it’s valid, Kitty gets her tuna. The token has three parts: Header.
Payload. Signature. The header says how the token was made. The payload has Kitty’s info. The signature proves it wasn’t changed. If a bad kitty edits the token? Signature breaks. and the Server rejects it. That's JSON web tokens, lightweight. Stateless. Easy for servers to verify. And used for authentication and access control.
A JSON Web Token (JWT) is a small, signed piece of text that a server hands you after you log in, so you can prove who you are on every later request without sending your password again.
Many APIs use it for their 'Bearer' tokens, and knowing what is inside one, and what isn't, saves you from some easy security mistakes.
Why a token at all
HTTP has no memory. Each request arrives on its own, so once you have logged in, the server needs a way to recognise you next time. Asking for the password on every click is out of the question. There are two common answers.
Server-side sessions: the server stores a session record and gives you a random session ID, usually in a cookie. On each request it looks the ID up.
Tokens such as JWTs: the server writes the facts it needs (who you are, and until when) into the token itself and signs it. On each request it checks the signature, and nothing has to be looked up.
That second approach is what 'stateless' means: the server keeps no record of the login. Any server that holds the key can check the token, which is why JWTs are popular for APIs, mobile apps and systems split across many services.
Once a token is verified, its contents answer two questions: who is this, and what are they allowed to do? A role claim, for example, can decide whether someone reaches the admin pages. That is the difference between authentication and authorisation, and a JWT is used for both.
The login flow
Here is the round trip, from password to protected page:
You send your username and password to the login endpoint.
The server checks the password. If it matches, it builds a JWT with your user ID and an expiry time, and signs it.
JWT, explained by cats. Kitty logs into her Tuna App. The server checks her password. All good. Kitty is allowed inside. But Kitty doesn’t want to log in again every time she clicks something. So the server gives Kitty a JWT.
a JSON Web Token. A little signed note that says: ‘This is Kitty. She’s verified.’ Kitty keeps this token. She sends it with every request. The server checks the signature. If it’s valid, Kitty gets her tuna. The token has three parts: Header.
Payload. Signature. The header says how the token was made. The payload has Kitty’s info. The signature proves it wasn’t changed. If a bad kitty edits the token? Signature breaks. and the Server rejects it. That's JSON web tokens, lightweight. Stateless. Easy for servers to verify. And used for authentication and access control.
The first two parts are JSON, encoded with Base64URL, a way of writing bytes using only characters that are safe in a URL. Decode them and you get the JSON straight back.
Header
The header says how the token was made:
{ "alg": "HS256", "typ": "JWT" }
alg names the signing algorithm. HS256 means HMAC with SHA-256, which uses one secret key that only the server knows.
Payload
The payload holds the facts the token vouches for, called claims:
{ "name": "Kitty", "job": "Developer" }
A real token usually carries a few registered claims as well, defined in the JWT standard:
Claim
Means
sub
Subject: who the token is about, usually a user ID
exp
Expiry: when it stops being valid, in seconds since 1970
iat
Issued at: when it was made
iss, aud
Issuer and audience: who made it, and who it is for
Signature
The signature ties the other two parts together. For HS256, the server takes the encoded header, a dot and the encoded payload, and runs them through HMAC-SHA256 with its secret key. Only someone with the key can produce the right signature for that exact header and payload.
Why tampering fails
Say someone edits the payload to give themselves a promotion:
{ "name": "Kitty", "job": "Admin" }
Re-encoding it is easy, since Base64URL is no secret. What they can't do is produce a matching signature, because they don't have the key. When the token arrives, the server recomputes the signature from the header and payload it received, compares it with the one attached, and finds they differ. The token is rejected.
So a signature guarantees integrity: nobody can change the token without the server noticing. It hides nothing, though.
Signed is not encrypted
Anyone holding a JWT can read its payload. Paste one into any JWT decoder and the claims appear in plain text. So:
Never put passwords, card numbers or other secrets in the payload.
Keep it small: the token travels with every request.
Always send it over HTTPS, so nobody can pick it up in transit.
When the contents really must be hidden, there is a separate format, JWE (JSON Web Encryption), but most apps only need a signed token.
Verifying one in code
In Node.js, the widely used jsonwebtoken package signs and verifies tokens:
verify checks the signature and the expiry together, and throws if either fails. Passing algorithms matters, for a reason covered under common mistakes below.
HS256 or RS256
HS256 uses one shared secret for both signing and checking. That suits a single server, or a few you control. But every service that verifies tokens then holds the key that can create them.
RS256 uses a key pair instead. The login server signs with a private key that never leaves it, and every other service verifies with the public key, which can't create tokens. It is the usual choice when many services, or other companies, need to check your tokens. ES256 does the same job with elliptic-curve keys.
The cost of being stateless
Because the server keeps no record, it can't easily take a token back. A stolen token works until it expires, and logging out on the client only deletes the client's copy.
The usual ways to live with this:
Short expiry: access tokens that last minutes rather than days limit the damage.
Refresh tokens: a longer-lived token, stored more carefully, that the app swaps for a new access token when the old one runs out. The server can keep a list of refresh tokens and cancel one, which brings back some state where it matters.
A deny list of revoked token IDs (the jti claim) for emergencies. It adds back a lookup, so keep it small.
If your app is one website talking to its own server, a plain session cookie is often simpler and easier to revoke. JWTs earn their keep when several services must trust the same login without sharing a session store.
Where to keep the token
In a browser there are two usual homes, each with a risk.
localStorage is easy to use from JavaScript, but so is any script injected through an XSS bug, which can read the token and send it away.
An HttpOnlycookie can't be read by JavaScript, which blunts XSS. The browser sends it automatically, though, so you need protection against cross-site request forgery (CSRF), such as the SameSite attribute.
Many teams choose the cookie and add CSRF protection.
Common mistakes
Decoding instead of verifying: reading the payload without checking the signature trusts whatever the client sends.
Accepting any algorithm: some older libraries trusted the token's own alg header, including none, which means no signature at all. Pin the algorithms you expect on the server.
A weak HS256 secret: a short or guessable secret can be brute-forced offline from a single token. Use a long random key.
No expiry: a token without exp stays valid for ever.
Treating the payload as private: it is only encoded.
Key takeaways
A JWT is a signed note from the server: a header, a payload and a signature, joined by dots.
The signature proves the token hasn't been changed: any edit breaks it, and the server rejects the token.
Anyone can read the payload, so keep secrets out of it.
JWTs are stateless, so any server with the key can verify them, but they are hard to revoke: keep them short-lived.
Always verify the signature, pin the algorithm and check the expiry.