What Is JWT? Structure, Signing & Safe Use
Three base64url chunks separated by dots β a header, a payload and a signature. Learn what each part proves, what it does not prove, and the five mistakes that turn a JWT into a security hole.
What you will learn
- Read a JWT and name its three parts
- Explain what the signature proves β and what it doesn't
- Use the standard claims (exp, iss, aud, sub) correctly
- Decide when a JWT beats a server-side session (and when it loses)
- Avoid the five classic JWT security mistakes
- What a JWT is
- Anatomy: the three parts
- How signing and verification work
- The standard claims
- When to use a JWT β and when not to
- Common mistakes
- Try it: JWT Decoder
- Frequently asked questions
What a JWT is
A JSON Web Token (JWT) is a compact, URL-safe way to pass a signed claim between two parties. It looks like this:
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IlZhbGV2IiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMn0.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
Three blocks, separated by dots: header.payload.signature. A server creates one after you log in, hands it to you, and you send it back with every request β usually in an Authorization: Bearer <token> header. The server verifies the signature and trusts the claims inside, without looking anything up in a database. That βno lookupβ property is the whole point β and, as we'll see, also the main weakness.
Anatomy: the three parts
Each part is base64url-encoded JSON (base64 with +// replaced by -/_ and padding removed, so it survives in a URL). Decode the example above and you get:
// Header β how the token is signed
{ "alg": "HS256", "typ": "JWT" }
// Payload β the claims (statements about the user)
{ "sub": "1234567890", "name": "Valev", "admin": true, "iat": 1516239022 }
// Signature β HMAC-SHA256 over header.payload, with a secret key| Part | Contents | Secret? |
|---|---|---|
| Header | Signing algorithm (alg) and type (typ) | No β readable by anyone |
| Payload | Claims: who you are, what you may do, when it expires | No β readable by anyone |
| Signature | Hash of header + payload, keyed with a secret | Yes β only the issuer can make it |
How signing and verification work
To create the signature, the issuer takes base64url(header) + "." + base64url(payload) and signs it:
HMAC-SHA256(secret, header + "." + payload) // HS256: shared secret RS256: sign with a private key, verify with a public key
Verification is the same computation in reverse: the server recomputes the signature over the header and payload it received, using its own secret key, and compares. If even one character of the payload was changed β say, flipping "admin": false to true β the signature no longer matches and the token is rejected.
Two algorithm families matter. Symmetric (HS256): one shared secret signs and verifies β simple, but anyone with the secret can forge tokens, so only the issuer may hold it. Asymmetric (RS256/ES256): a private key signs, a public key verifies β the verifier can be a different service, which is how βlogin with Googleβ style federation works.
The standard claims
| Claim | Meaning | Why it matters |
|---|---|---|
iss | Issuer β who created the token | Reject tokens from strangers |
sub | Subject β whose token this is (user ID) | The identity the app acts on |
aud | Audience β which service the token is for | Stops a token for one app being reused in another |
exp | Expiry β Unix time after which it is invalid | Limits the damage of a stolen token |
iat | Issued at | Detect tokens made before a password change |
nbf | Not before | Tokens that only become valid later |
On top of these, applications add their own claims β roles, permissions, a display name. Keep the payload small: the token is sent with every request, so a 5 KB token is a tax on every single call.
When to use a JWT β and when not to
JWTs shine when verification must happen without a database round-trip, or across services that don't share a session store: APIs, microservices, and single sign-on. The verifier needs only the key.
They lose in one important way: you cannot easily revoke one. A server-side session can be deleted the moment a user logs out or changes a password; a JWT stays valid until it expires, because there is nothing to delete. The standard mitigations are short expiry times (minutes, not days) plus refresh tokens β a long-lived token that is only ever sent to the login endpoint to mint fresh short-lived JWTs β or a revocation list, which quietly reintroduces the database lookup the JWT was meant to avoid.
Rule of thumb: if you have one app and one database, a classic session cookie is simpler and safer. Reach for JWT when you have many services, or when the token must cross a trust boundary.
Common mistakes
- Trusting a client-decoded token. Decoding proves nothing β only signature verification does. The
admin: truein a decoded payload is a claim, not a fact, until the signature checks out. - Accepting
alg: none. An unsigned token must be rejected. Libraries that still accept it are the oldest JWT vulnerability in the book β and it still shows up. - Weak or leaked secrets. HS256 with the secret
secretis forgeable in seconds. Use a long random secret, rotate it, and never commit it. - No expiry (
exp). A stolen token then works forever. Set a shortexpand use refresh tokens. - Putting secrets in the payload. Base64url is not encryption β anyone can read it. See the callout above.
- Storing tokens in localStorage. Any cross-site scripting (XSS) hole lets an attacker read it. HttpOnly cookies are the safer home for browser tokens.
Try it: JWT Decoder
Paste a token into the JWT Decoder and watch it split into header, payload and human-readable dates β the fastest way to see the structure this guide describes.
Keep learning
Frequently asked questions
Is a JWT encrypted?
No. A standard JWT (JWS) is signed, not encrypted β the payload is base64url, which anyone can decode. Encryption is a separate format, JWE, used when the contents themselves must stay secret.
How do I revoke a JWT when a user logs out?
You can't delete it directly β it stays valid until exp. The practical answers are short expiry with refresh tokens, or a server-side denylist of revoked token IDs (the jti claim) checked on sensitive endpoints.
JWT vs session cookie β which should I choose?
A session cookie for a single app with a database: simpler, instantly revocable. A JWT for APIs and microservices where verifiers can't share a session store, or where tokens cross service boundaries. Many systems use both: a session for the browser, JWTs for service-to-service calls.
Where should I store a JWT in the browser?
In an HttpOnly, Secure, SameSite cookie β JavaScript can't read it, so XSS can't steal it. localStorage is convenient but readable by any script on the page, including an injected one.
Can I decode a JWT without the secret?
Yes β decoding the header and payload needs no key at all; only verifying the signature does. That is why the JWT Decoder tool can show you a token's contents instantly, and why you must never put secrets in the payload.