JWT & Token-Based Authentication

Anatomy of a JWT

A JWT has three base64url-encoded parts separated by dots:

# A real JWT (line breaks added for readability)
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.    # Header
eyJzdWIiOiIxMjMiLCJuYW1lIjoiSmFuZSIsInJ  # Payload
vbGUiOiJhZG1pbiIsImlhdCI6MTc0MzYzODQwMC
wiZXhwIjoxNzQzNjQyMDAwfQ.
SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c  # Signature

Header

The header specifies the signing algorithm and token type:

{
  "alg": "HS256",    // HMAC-SHA256 (symmetric)
  "typ": "JWT"
}

Payload (Claims)

The payload contains claims — statements about the user and metadata. There are registered (standard), public, and private claims:

{
  "sub": "user-123",        // Subject (user ID) — registered
  "name": "Jane Doe",       // Public claim
  "role": "admin",          // Private claim (your app's data)
  "iat": 1743638400,        // Issued At — registered
  "exp": 1743642000,        // Expiration — registered (1 hour later)
  "iss": "myapp.com",       // Issuer — registered
  "aud": "api.myapp.com"    // Audience — registered
}

Signature & Signing Algorithms

The signature ensures the token hasn't been tampered with. Different algorithms serve different use cases:

# Python: Sign and verify JWT with RS256 (asymmetric)
import jwt  # PyJWT library

# Sign with private key
private_key = open('private.pem').read()
token = jwt.encode(
    {'sub': 'user-123', 'role': 'admin', 'exp': 1743642000},
    private_key,
    algorithm='RS256'
)

# Verify with public key (can be shared freely)
public_key = open('public.pem').read()
decoded = jwt.decode(token, public_key, algorithms=['RS256'])
print(decoded['sub'])  # user-123

Access Tokens vs Refresh Tokens

A common pattern: issue a short-lived access token for API calls and a long-lived refresh token to get new access tokens without re-login.

// Token refresh flow (client-side)
async function fetchWithAuth(url, options = {}) {
  let response = await fetch(url, {
    ...options,
    headers: { ...options.headers, 'Authorization': `Bearer ${accessToken}` }
  });

  // If 401, try refreshing the token
  if (response.status === 401) {
    const refreshResponse = await fetch('/api/auth/refresh', {
      method: 'POST',
      credentials: 'include'  // sends httpOnly refresh cookie
    });

    if (refreshResponse.ok) {
      const { access_token } = await refreshResponse.json();
      accessToken = access_token;  // update in-memory token

      // Retry original request with new token
      response = await fetch(url, {
        ...options,
        headers: { ...options.headers, 'Authorization': `Bearer ${accessToken}` }
      });
    } else {
      // Refresh failed — redirect to login
      window.location.href = '/login';
    }
  }

  return response;
}

Common JWT Security Pitfalls

# SAFE: Hardcode the algorithm — never trust the token's header
decoded = jwt.decode(
    token,
    public_key,
    algorithms=['RS256'],  # Only accept RS256
    audience='api.myapp.com',
    issuer='myapp.com'
)

# DANGEROUS: Accepting any algorithm from the token
# decoded = jwt.decode(token, key, algorithms=jwt.get_unverified_header(token)['alg'])

When NOT to Use JWTs

• You need instant revocation — JWTs can't be revoked until they expire (without a blocklist, which defeats the "stateless" benefit)
• You have a single server — sessions with server-side storage are simpler and more secure
• You need to store sensitive data — JWT payloads are readable by anyone. Use server-side sessions or JWE (encrypted JWT)
• Your tokens get very large — JWTs are sent with every request. Large payloads = bigger requests = slower performance

Interview Questions