JWT and token authentication: a practical security guide.

JWTs are everywhere, misused in about half those places, and the source of a disproportionate number of auth bugs. The core concept is sound — a signed, self-contained token that lets a server verify a claim without a database lookup — but the implementation details matter enormously. The wrong signing algorithm, tokens that never expire, JWTs stored in localStorage, missing audience validation: any of these turns a stateless auth system into a security liability. This post covers the structure, the common pitfalls, and the refresh token rotation pattern that makes JWTs actually safe to use in production.

JWT structure and what each part means

A JWT is three base64url-encoded sections separated by dots: header.payload.signature.

// Header — algorithm and token type
{
  "alg": "RS256",    // Signing algorithm — use RS256 or ES256, never HS256 in distributed systems
  "typ": "JWT"
}

// Payload — claims about the subject
{
  "sub": "user-uuid-here",          // Subject: who this token represents
  "iss": "https://sso.example.com", // Issuer: who created this token
  "aud": "api.example.com",         // Audience: who this token is intended for
  "exp": 1740499200,                // Expiry: Unix timestamp (ALWAYS include this)
  "iat": 1740495600,                // Issued-at timestamp
  "jti": "unique-token-id",         // JWT ID: enables revocation tracking
  "roles": ["user"],                // Custom claims: application-specific data
  "email": "alice@example.com"
}

// Signature — cryptographic proof the header+payload haven't been tampered with
// For RS256: RSASSA-PKCS1-v1_5 signature using the issuer's private key
// Verified with the corresponding public key — no secret sharing required

Algorithm choice: RS256, ES256, or HS256?

• HS256 (HMAC-SHA256): symmetric — the same secret signs and verifies. Every service that needs to verify tokens must know the secret. If any service is compromised, the entire signing secret is exposed and arbitrary tokens can be forged. Only acceptable for single-service, non-distributed systems.
• RS256 (RSA-SHA256): asymmetric — private key signs, public key verifies. The signing key never leaves the auth server. All other services verify with the public key, which can be published (e.g. at a JWKS endpoint). The standard choice for most production systems.
• ES256 (ECDSA-SHA256): asymmetric like RS256 but produces much smaller signatures and is faster. Preferred over RS256 for new systems — identical security model, better performance.

Short-lived access tokens with refresh token rotation

The fundamental tension with JWTs: they're stateless (good for scalability) but also irrevocable — once issued, a JWT is valid until it expires. This is why access tokens must be short-lived (15 minutes is standard) and refresh tokens must rotate on every use:

// Token issuance at login
async function login(email, password) {
  const user = await verifyCredentials(email, password);

  // Short-lived access token — 15 minutes
  const accessToken = await signJWT({
    sub: user.id,
    email: user.email,
    roles: user.roles,
    iss: 'https://auth.example.com',
    aud: 'api.example.com',
    exp: Math.floor(Date.now() / 1000) + 900,  // 15 min
    jti: crypto.randomUUID(),
  }, privateKey, 'ES256');

  // Long-lived refresh token — stored server-side, rotated on each use
  const refreshToken = crypto.randomBytes(32).toString('hex');
  await db.refreshTokens.create({
    token: await hash(refreshToken),   // Store hash, not plaintext
    userId: user.id,
    expiresAt: new Date(Date.now() + 30 * 24 * 60 * 60 * 1000), // 30 days
    family: crypto.randomUUID(),  // Token family for rotation detection
  });

  return { accessToken, refreshToken };
}

// Token refresh — rotate the refresh token on every use
async function refreshAccessToken(refreshToken) {
  const stored = await db.refreshTokens.findByHash(await hash(refreshToken));

  if (!stored || stored.expiresAt < new Date()) {
    throw new Error('Invalid or expired refresh token');
  }

  // Refresh token rotation: invalidate the used token
  await db.refreshTokens.delete(stored.id);

  // Detect reuse: if this token was already used, the family is compromised
  if (stored.usedAt) {
    // Someone is replaying a used refresh token — invalidate the entire family
    await db.refreshTokens.deleteFamily(stored.family);
    throw new Error('Refresh token reuse detected — all sessions invalidated');
  }

  // Issue new tokens
  return login_internal(stored.userId);
}

Token storage: where to put JWTs on the client

• HttpOnly cookies: the browser sends automatically, inaccessible to JavaScript — eliminates XSS token theft. Vulnerable to CSRF, mitigated with SameSite=Strict or CSRF tokens. The recommended storage for web apps.
• Memory (JS variable): not persisted, survives page navigation in SPAs. Secure from XSS, lost on refresh. Good for access tokens in SPAs when combined with HttpOnly refresh token cookies.
• localStorage/sessionStorage: readable by any JavaScript on the page. A single XSS vulnerability anywhere on your domain exposes all stored tokens. Do not store JWTs here.

Token revocation when you need it

Sometimes you must invalidate a token before it expires — user logs out, password changed, account suspended. The options, in order of simplicity:

• Short expiry: 15-minute access tokens limit the revocation window to 15 minutes maximum. Often acceptable.
• Revocation list (blocklist): store invalidated jti values in Redis with expiry matching the token expiry. Check on every request. Fast but requires a Redis read per API call.
• Reference tokens: the token is an opaque ID that the resource server exchanges for claims at the auth server. Fully revocable, but eliminates the stateless benefit of JWTs. Appropriate for high-security operations.