JSON Web Tokens (JWT)

What a JWT looks like

A JWT (JSON Web Token, said "jot") is three pieces of text joined by dots: header.payload.signature. The header says how it was signed. The payload holds claims, which are facts like "user 42, expires at 10:15". The signature proves the server made it and nobody changed it.

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9      <- header  {"alg":"HS256","typ":"JWT"}
.
eyJzdWIiOiI0MiIsIm5hbWUiOiJBc2hhIiwiZXhwIjoxOTAwMDAwMDAwfQ
                                          <- payload {"sub":"42","name":"Asha","exp":1900000000}
.
v-5a3JP0uhw6kTBBLn0jq7yvz6nFx2PctEvhWBfF56A <- signature (HMAC-SHA256)

base64url: encoding, not hiding

Each part is base64url encoded. Base64 turns bytes into letters, digits and a few symbols; the "url" version uses - and _ instead of + and / and drops the = padding, so the token is safe in URLs. Encoding is not encryption: anyone can decode the payload in one line.

Common claims

Signing: HS256 or RS256

// Example only: runs on a server with Node.js and the jose package
import { SignJWT, jwtVerify } from 'jose';
const secret = new TextEncoder().encode(process.env.JWT_SECRET);

const token = await new SignJWT({ role: 'customer' })
  .setProtectedHeader({ alg: 'HS256' })
  .setSubject('42')
  .setIssuedAt()
  .setExpirationTime('15m')
  .sign(secret);

// Verify checks the signature AND exp; pin the allowed algorithm
const { payload } = await jwtVerify(token, secret, { algorithms: ['HS256'] });

Short life, refresh tokens and storage

Keep access tokens short-lived (5 to 15 minutes). A refresh token is a second, long-lived token used only to get a new access token. Store refresh tokens on the server so you can cancel them, and rotate them (give a new one each time).

In a browser, keep tokens in an HttpOnly, Secure, SameSite cookie rather than localStorage, because any XSS bug can read localStorage. Mobile apps use the phone's secure storage (Keychain or Keystore).

Logging out a JWT

A JWT stays valid until exp, even after the user presses logout, because the server does not look it up. To block one early you need a denylist: store its id (the jti claim) until it would expire, and check that list on each request. In practice: short expiry plus deleting the refresh token.