JWT
JSON Web Token: a compact, self-contained token for transmitting claims between parties. The server can verify it without a database lookup.
What is JWT?
In short
A JWT (JSON Web Token) is a compact, URL-safe token that carries a set of signed claims (like user ID, role, and expiry) as JSON, so a server can verify who a request belongs to by checking the signature alone, with no database lookup. It has three Base64URL-encoded parts separated by dots: a header, a payload, and a cryptographic signature.
What a JWT actually is
A JWT is a string with three parts joined by dots: header.payload.signature. Each part is Base64URL encoded, so the whole thing is plain text you can paste into a header or a URL. A typical one starts with eyJ because that is what the encoded JSON header begins with.
The header says which signing algorithm was used, for example HS256 or RS256. The payload holds the claims: small facts about the user or the token itself. Standard claims defined in RFC 7519 include sub (subject, usually the user ID), exp (expiry as a Unix timestamp), iat (issued at), and iss (issuer). You can add your own claims too, like role or tenant ID.
The signature is the important part. The server computes it over the header and payload using a secret key, then attaches it. Anyone can read a JWT, but only the holder of the key can produce a valid signature. That is why a JWT is signed, not encrypted. Never put a password or a credit card number in the payload, because it is readable by anyone who has the token.
How verification works without a database
When a client sends a JWT back on each request, the server re-runs the signing function over the header and payload with its key and checks that the result matches the signature on the token. If it matches, the claims have not been tampered with and the server trusts them. It then checks exp to make sure the token has not expired.
This is the whole point. With a classic session cookie, the server holds a random session ID and must look it up in a session store or database on every request to find out who you are. With a JWT, the user identity travels inside the token itself, so a stateless API server can authenticate the request using only the key in memory and some math. No round trip to a store.
There are two families of signing. HMAC algorithms like HS256 use one shared secret to both sign and verify, which is simple but means every verifier also holds the signing key. Asymmetric algorithms like RS256 or ES256 sign with a private key and verify with a public key, so you can hand the public key to many services without letting them mint tokens. Large identity providers use RS256 and publish their public keys at a JWKS endpoint.
When to use it, and the trade-offs
JWTs fit stateless, distributed setups well: APIs spread across many servers, microservices that need to trust a token issued by a central auth service, and single sign-on. OAuth 2.0 access tokens and OpenID Connect ID tokens are very commonly JWTs.
The hard trade-off is revocation. Because the server does not check a store, a valid unexpired JWT keeps working even after you log the user out or ban them. You cannot easily kill one token. The usual answer is to keep access tokens short lived, often 5 to 15 minutes, and pair them with a longer-lived refresh token that is checked against a database when issuing a new access token. That gives you most of the stateless speed while keeping a revocation point.
Security mistakes are common and worth naming. The alg:none attack lets a forged token claim no signature is needed, so always pin the expected algorithm on the server instead of trusting the header. Keep secrets long and random for HS256, never confuse the signing key with the verification key when mixing algorithms, and always validate exp, iss, and the audience claim aud. Because JWTs are often larger than a session ID, sending them on every request adds bytes, which matters at high volume.
A concrete example
Say a user logs in to an API. The auth service checks the password once, then issues a JWT with sub set to the user ID, role set to admin, and exp set to 15 minutes from now, signed with RS256. The browser stores it and sends it on each request as Authorization: Bearer eyJ...
An order service and a billing service, running on different machines, each hold only the auth service public key. When a request arrives, each one verifies the signature locally, reads role admin from the payload, and decides whether to allow the action. Neither service ever talks to the auth database to authenticate the call.
Fifteen minutes later the token expires and requests start failing with 401. The browser quietly sends its refresh token to the auth service, which does check its database, confirms the user is still active, and mints a fresh 15-minute JWT. The user never notices, and a banned user stops working within at most 15 minutes.
Where it is used in production
Auth0 / Okta
Issues OAuth and OpenID Connect access and ID tokens as RS256-signed JWTs, with public keys served from a JWKS endpoint for verification.
Firebase Authentication
Hands clients a signed JWT after login that backend services and Firebase Security Rules verify to authorize reads and writes.
Kubernetes
Service account tokens are JWTs that pods present to the API server, which validates the signature and bound claims to authorize calls.
AWS
Amazon Cognito issues JWTs for user pools, and API Gateway JWT authorizers verify them to gate access to backend endpoints.
Frequently asked questions
- Is a JWT encrypted?
- No. A standard signed JWT (a JWS) is only signed, so anyone holding the token can Base64URL-decode and read the payload. Signing proves the claims were not changed, it does not hide them. If you need the contents secret, use JWE (encrypted JWT) and still send it over HTTPS, and never put passwords or other secrets in a normal JWT.
- What is the difference between a JWT and a session cookie?
- A session cookie holds a random ID, and the server looks that ID up in a store on every request to find your identity, which makes it stateful and easy to revoke. A JWT carries your identity inside the signed token, so the server verifies it with a key and no lookup, which is stateless and fast but hard to revoke before it expires.
- How do I revoke or log out a JWT?
- You cannot directly invalidate a valid, unexpired JWT because the server does not check a store. The practical pattern is short-lived access tokens (5 to 15 minutes) plus a long-lived refresh token checked against a database, or a server-side denylist of token IDs (the jti claim) for the rare cases you must kill a specific token early.
- Where should I store a JWT in a browser?
- The safest option is an HttpOnly, Secure, SameSite cookie, which JavaScript cannot read so it resists XSS token theft, though it needs CSRF protection. Storing it in localStorage is convenient but exposes it to any XSS on the page. Avoid putting long-lived tokens anywhere a script can reach.
- What is the alg:none vulnerability?
- Some libraries used to honor a token header that set alg to none, meaning no signature was required, which let an attacker forge any claims they wanted. Always configure your verifier to require a specific expected algorithm and reject none, rather than trusting the algorithm the incoming token declares.
Learn JWT hands-on
This page explains the idea. The full lesson lets you step through the ring as servers join and leave, read the implementation, and check yourself with a quiz. It is one of 760+ lessons in the System Design Masterclass, from your first API call to distributed consensus. Eleven Foundation lessons are free, no signup. Lifetime access is ₹499 in India or $7.99 worldwide, one payment, no subscription.
Related lessons
Lessons that touch on JWT as part of a larger topic.
JWT Sessions
Using JWTs as session tokens: the trade-offs, pitfalls, and best practices
intermediate · security architecture
Session Management
How servers remember who you are between requests in a stateless protocol
foundation · core fundamentals
Distributed Session Management
Managing user sessions across multiple servers, sticky sessions, centralized stores, and token-based approaches
intermediate · security architecture
Service-to-Service Authentication
How microservices prove their identity to each other, mTLS, JWTs, API keys, and SPIFFE
intermediate · security architecture
See also
Related glossary terms you might want to look up next.
OAuth
An authorization framework that lets users grant third-party apps limited access to their accounts without sharing passwords. Powers 'Sign in with Google.'
Session
A way to maintain state across multiple HTTP requests. The server stores data about a user and gives them a session ID (usually in a cookie).
Stateless
A system where each request contains all the information needed to process it. The server doesn't remember previous requests. Easier to scale horizontally.
Throttling
Slowing down the rate of processing requests instead of rejecting them outright. The gentler cousin of rate limiting.
SSL/TLS
Cryptographic protocols that encrypt data in transit between client and server. TLS is the modern successor to SSL. The 'S' in HTTPS.
CORS
Cross-Origin Resource Sharing: a security mechanism that controls which domains can access your API. The browser enforces it; the server configures it.