JWT (JSON Web Tokens)

Take any JWT — those long strings that look like this:

Decode the middle part from base64 and you'll find plain JSON. Not encrypted, not hashed. Just encoded.

This surprises a lot of people. "So anyone can read my token?" Yes. But no one can forge one without the secret key. Understanding this distinction is the key to understanding JWTs.

Press enter or space to select a node. You can then use the arrow keys to move the node around. Press delete to remove it and escape to cancel.

Press enter or space to select an edge. You can then press delete to remove it or escape to cancel.

algobase.dev

A JWT is three base64url-encoded JSON objects joined by dots: header.payload.signature. The header declares the token type and signing algorithm (RS256 for asymmetric, HS256 for symmetric). The payload contains claims — standard ones like sub (subject/user ID), exp (expiration timestamp), iat (issued at) — plus any custom claims you add like roles, tenant ID, or plan tier. Critically: the payload is just base64-encoded, not encrypted. Anyone who intercepts the token can read the claims. The signature prevents forgery — if anyone tampers with the payload (changes "user" to "admin"), the signature will not match and the token is rejected.

1 / 10.5×1×2×3×Playground

JWT three-part structure — header.payload.signature with base64url encoding

Structure of a JWT

A JWT is three base64url-encoded sections joined by dots:

Header

The header is a JSON object specifying the token type and the signing algorithm:

alg tells the verifier which algorithm was used to create the signature. Common options:

• HS256: HMAC-SHA256 (symmetric, same secret for signing and verifying)
• RS256: RSA-SHA256 (asymmetric, private key signs, public key verifies)
• ES256: ECDSA with P-256 (asymmetric, smaller keys than RSA)

Payload

The payload contains the actual data — these are called claims:

Standard claims (defined in the JWT spec):

• sub (subject) — who the token is about, typically a user ID
• iss (issuer) — who created the token
• aud (audience) — who the token is intended for
• exp (expiration) — Unix timestamp after which the token is invalid
• iat (issued at) — when the token was created
• nbf (not before) — the token isn't valid before this timestamp

Custom claims: Anything else you add. Roles, permissions, tenant ID, plan tier — you can put any JSON-serializable data here. Just be mindful that this data is included in every request.

Signature

The signature is what makes the token trustworthy. It's computed by taking the encoded header + encoded payload and signing them with a secret key:

When the server receives a token, it recomputes the signature using the same key and compares it to the signature in the token. If they match, the payload is authentic and unmodified. If someone tampers with the payload (changes "roles": ["user"] to "roles": ["admin"]), the signature won't match and the token is rejected.

Press enter or space to select a node. You can then use the arrow keys to move the node around. Press delete to remove it and escape to cancel.

Press enter or space to select an edge. You can then press delete to remove it or escape to cancel.

algobase.dev

JWT verification requires no database lookup — just cryptography. The auth service splits the token into its three parts, recomputes the expected signature from the received header and payload using its secret key, and compares it to the signature in the token. If they match, the payload is authentic and unmodified. Then it checks the exp claim — if expired, reject. If both checks pass, the sub and any other claims are forwarded to the backend, which now knows who the user is and what they can do. Any server with the secret key can verify any token independently — this is what makes JWTs stateless and horizontally scalable. For multi-service architectures, prefer asymmetric signing (RS256): only the auth service holds the private key, and other services verify with the public key.

1 / 10.5×1×2×3×Playground

Cryptographic verification — server recomputes HMAC, compares to token signature

How JWT Verification Works Without a Database

This is the elegant part. When your API receives a request with a JWT:

1. Split the token into header, payload, and signature
2. Recompute the expected signature from the header + payload using your secret key
3. Compare to the provided signature — if they match, the token is valid
4. Check the exp claim — if expired, reject
5. Read the sub and any other claims — you now know who the user is and what they're allowed to do

No database lookup required. The server validates the token purely with cryptographic operations. This is what makes JWTs scale horizontally — any server with the secret key can validate any token, independently.

Compare this to session-based auth, where every request requires a Redis lookup. With JWTs, your backend services can validate tokens in microseconds with no external dependency.

Symmetric vs Asymmetric Signing

Symmetric (HS256): A single secret key is used for both signing and verifying. Fast and simple. Works well when the same service issues and verifies tokens. Problem: every service that needs to verify tokens needs the secret — which means it can also issue tokens. Sharing a secret broadly increases the attack surface.

Asymmetric (RS256, ES256): A private key signs tokens; a public key verifies them. Only the auth service holds the private key. Every other service gets the public key, which lets them verify but not create tokens. This is the right approach when:

• Multiple services need to verify tokens
• You're issuing tokens for third-party consumption
• You want to make your public key available via a JWKS (JSON Web Key Set) endpoint so clients can discover it automatically

Most identity providers (Auth0, Cognito, Google) publish their public keys at a well-known URL (e.g., https://your-domain.auth0.com/.well-known/jwks.json), which is how your API knows how to verify tokens they issue.

JWT Pitfalls

Expiry — Set It Short

JWTs are irrevocable until they expire. If a token is stolen or a user's account is suspended, you can't invalidate it. It stays valid until exp.

The solution is short expiry times. Access tokens should expire in 15 minutes to 1 hour. Pair them with refresh tokens: longer-lived tokens (7-30 days) stored securely, used only to get a new access token when the current one expires.

If you need true instant revocation, maintain a token blocklist in Redis: a set of token IDs (jti claim) that have been revoked. Check every incoming token against the blocklist. This re-introduces state but preserves the scalability benefits for the 99.9% of valid tokens.

The "none" Algorithm Vulnerability

Early JWT libraries had a catastrophic bug: if you sent a token with "alg": "none" in the header, some libraries accepted it as valid without verifying the signature. This let attackers craft arbitrary tokens.

Modern libraries have fixed this, but always configure your library to explicitly whitelist allowed algorithms. Never accept "alg": "none".

Key Rotation

If your signing key is compromised, all tokens signed with it must be considered invalid. You need a process for rotating keys without logging everyone out simultaneously:

• Assign a key ID (kid) to each key
• Include the kid in the JWT header
• Support multiple active keys simultaneously during rotation
• Retire old keys after all tokens signed with them have expired

What to Put in localStorage vs HttpOnly Cookies

This is a genuine security debate:

localStorage:

• Easy to implement, accessible by JavaScript
• Vulnerable to XSS — any JavaScript on your page can read it, including injected malicious scripts

HttpOnly Cookie:

• Not accessible by JavaScript — XSS attacks can't steal it
• Automatically sent with requests
• Vulnerable to CSRF — you need CSRF tokens or SameSite cookie attribute as mitigation
• Cross-origin complexity

The modern consensus: Store tokens in HttpOnly, Secure, SameSite=Strict cookies. Use CSRF protection. Avoid localStorage for anything security-sensitive.

A third option gaining traction: store tokens in memory (a JavaScript variable). Tokens are lost on page refresh, but you can silently re-issue them via a refresh token in an HttpOnly cookie. This eliminates both XSS and CSRF risks at the cost of some implementation complexity.

Summary

JWTs are a powerful tool for stateless authentication — they carry identity and claims without requiring server-side session storage. The structure is always header.payload.signature: the payload is readable by anyone, but the signature is cryptographically verified, making forgery impossible without the secret key. Verification requires no database lookup — just cryptography — which is what makes JWTs scale horizontally. Use asymmetric signing (RS256/ES256) when multiple services need to verify tokens, keep access token expiry short (15–60 min) and pair with refresh tokens for long-lived sessions, and store tokens in HttpOnly cookies rather than localStorage. The classic pitfalls — algorithm confusion, missing expiry checks, and unmanaged key rotation — are avoidable once you understand them.

JWTs are not magic — they're base64-encoded JSON with a signature. Understanding exactly what that means makes you a much safer implementer of authentication systems.