JWT explained
A signed, self-describing token that lets a server trust a request without looking anything up.
A JSON Web Token packs claims into three base64url parts — header.payload.signature — and signs them. Anyone can read the payload, but only the holder of the key can forge the signature, so the server verifies a token cryptographically instead of hitting a session store. That makes auth stateless, but means you never put secrets in the payload and always set an expiry.
Log in
The client sends credentials to the auth server, which verifies them the usual way — checking a password hash or an OAuth grant. This is the only step that touches the user database; everything after is designed to avoid doing so again.
Build header + payload
The server creates two JSON objects: a header naming the algorithm (like {"alg":"HS256","typ":"JWT"}) and a payload of claims (sub, iss, exp, iat, plus custom fields like role). Each is base64url-encoded — a URL-safe encoding, not encryption — and joined with a dot.
Sign it
The server computes a signature over the encoded header and payload using a secret key (HMAC-SHA256) or a private key (RSA/ECDSA). The signature is appended as the third part, producing header.payload.signature. Changing even one byte of the first two parts invalidates the signature.
Return and store
The finished token goes back to the client, which stores it — commonly in memory, or in an HttpOnly cookie. The server keeps nothing: it does not remember that this token exists, which is exactly what makes the scheme stateless.
Send on every request
For each subsequent call the client attaches the token, usually in an Authorization: Bearer <token> header. The token itself carries the identity and claims, so the request is self-describing — no session lookup is needed to know who is calling.
Verify
The API server recomputes the signature with its key and compares it; a match proves the token was issued by someone holding the key and hasn't been altered. It then checks the claims — is exp in the future, is iss expected — before trusting the identity inside.
Expiry and refresh
Because the server can't easily un-issue a token, tokens carry a short exp and simply stop being accepted after it. A longer-lived refresh token, exchanged at the auth server, mints a fresh access token so the user isn't logged out every few minutes.
The problem JWTs solve
Classic web authentication is stateful: when you log in, the server creates a session, stores it in memory or a database, and hands you an opaque session ID in a cookie. Every later request carries that ID, and the server looks it up to remember who you are. This works, but the lookup is the catch — it ties every request to a shared session store, which becomes a bottleneck and a coordination problem the moment you run more than one server.
A JSON Web Token (JWT) flips this around. Instead of storing session state on the server and handing out a meaningless ID, the server hands out a token that *contains* the state and is cryptographically signed so it can't be forged. Now any server holding the verification key can validate the token on its own, with no database lookup and no shared session store. That property — stateless authentication — is why JWTs are everywhere in APIs, microservices, and single-page apps: they let a fleet of servers trust a request without coordinating.
Three parts: header.payload.signature
A JWT is a single string with three parts separated by dots, and you can spot one instantly by those two dots: xxxxx.yyyyy.zzzzz.
- Header — a small JSON object naming the token type and the signing algorithm, e.g.
{"alg":"HS256","typ":"JWT"}. It tells the verifier how the signature was made. - Payload — a JSON object of claims: statements about the user and the token. This is where identity and metadata live.
- Signature — a cryptographic seal computed over the first two parts, which is what makes the token trustworthy.
Each of the first two parts is base64url-encoded — a URL-safe variant of base64 that swaps the characters that would break inside a URL or header. This is critical to understand: base64url is *encoding, not encryption*. It scrambles nothing and hides nothing; anyone can paste the token into a decoder and read every claim. The encoding exists only to make arbitrary JSON safe to transmit as a compact ASCII string, never to keep it secret.
Signing and verification
The signature is the entire point of a JWT. To create it, the server takes the encoded header and payload, joins them with a dot, and runs them through the algorithm named in the header using a key. There are two families:
- HMAC (symmetric), e.g.
HS256— a single shared secret both signs and verifies. Fast and simple, but every party that can verify can also forge, so the secret must stay on trusted servers. - RSA / ECDSA (asymmetric), e.g.
RS256,ES256— a private key signs and a matching public key verifies. This lets you distribute the public key widely so many services can verify tokens they could never mint, which is ideal for a system with one issuer and many consumers.
Verification reverses the process: the receiver recomputes the signature over the header and payload it received and compares it to the one attached. If a single byte of the payload was changed in transit, the recomputed signature won't match and the token is rejected. A valid signature therefore proves two things at once — integrity (the token wasn't altered) and authenticity (it was issued by someone holding the key).
Standard claims and what belongs inside
The payload can hold any JSON, but a set of registered claims are standardized so tools agree on their meaning:
iss(issuer) — who created and signed the token.sub(subject) — who the token is about, usually the user ID.exp(expiration) — a Unix timestamp after which the token must be rejected.iat(issued-at) — when it was created.aud(audience) — who the token is intended for.
Alongside these you add your own custom claims — a role, a tenant ID, a set of scopes — so the receiving service can make authorization decisions straight from the token. But the golden rule follows directly from the encoding: never put anything secret in the payload. Passwords, API keys, or private personal data would be readable by anyone who intercepts the token. The payload is for identity and coarse authorization data that you're comfortable being public; secrets stay on the server.
Statelessness, expiry, and refresh
Statelessness is a genuine superpower and a genuine trap. Because the server keeps no record of issued tokens, there is no simple "log this user out everywhere" switch — a validly signed, unexpired token is accepted no matter what, even if the user changed their password five minutes ago. You cannot easily revoke what you never stored.
The standard mitigation is short-lived access tokens plus refresh tokens. The access token that rides on every API call is given a short exp — minutes to an hour — so a stolen token is only useful briefly. When it expires, the client presents a longer-lived refresh token to the auth server to obtain a fresh access token, without forcing the user to log in again. The refresh token is the only thing the server may track and revoke, which restores a revocation point while keeping the hot path stateless.
In practice, treat a JWT as a bearer credential: whoever holds it is trusted, so protect it like a password. Send it only over HTTPS, prefer storing it in an HttpOnly cookie to keep JavaScript (and XSS) away from it, always validate the signature *and* the exp and iss claims on every request, and pin the accepted algorithm on the server so an attacker can't talk you into verifying with a weaker one. Done that way, JWTs give you scalable, self-describing auth; done carelessly, they hand attackers a forgeable pass.
A JWT is three base64url-encoded parts joined by dots: header . payload . signature.
The header names the signing algorithm; the payload holds claims; the signature seals them.
Signing uses a secret (HMAC) or a private key (RSA/ECDSA); verification re-checks the signature.
Standard claims — iss, sub, exp, iat — describe who issued it, who it's about, and when it dies.
The payload is only encoded, not encrypted — readable by anyone, so never put secrets in it.
Statelessness is the point and the catch: you can't easily revoke a token, so keep exp short and use refresh tokens.
Quick quiz
Why must you never put a password or secret in a JWT payload?
What does verifying the signature actually prove?
Sessions, cookies, JWT & OAuth 2.0
How a server remembers who you are — and who let you in.
JWT vs PASETO
One format gives you infinite flexibility and a loaded footgun; the other takes the gun away.
Access control explained
First prove who you are, then the system decides what you're allowed to touch.
REST API authentication methods
Six ways to prove who's calling your API — and what each one costs you.