JWT Authentication Explained —
How the Full Flow Works

JWT authentication explained: a JWT replaces the server's need to look up a session in a database on every request — the token itself contains the user's identity and permissions, signed by the server so it can't be tampered with, which is why understanding the full issuance and verification flow is essential before trusting any library's "just works" abstraction.

The Full JWT Authentication Flow

The complete flow has eight steps. Each one matters — skipping the mental model of any step is how subtle security bugs sneak in.

What's Inside the JWT

Every JWT is three Base64Url-encoded segments separated by dots. The middle segment — the payload — contains all the claims the server issued. It is not encrypted: anyone who holds the token can read its contents.

{
  "alg": "HS256",
  "typ": "JWT"
}

{
  "sub":   "user_123",
  "email": "alice@example.com",
  "role":  "admin",
  "iat":   1716239022,
  "exp":   1716242622
}

HMAC vs RSA Signing: HS256 vs RS256

The signing algorithm determines how many parties can issue and verify tokens — which matters enormously in distributed systems.

Use HS256 when a single application both issues and verifies tokens — the shared secret never leaves one system. Use RS256 when multiple services need to verify tokens independently: each service holds only the public key, while the private signing key stays exclusively with the authentication service.

Access Tokens + Refresh Tokens — The Standard Pattern

Issuing one long-lived token creates an obvious problem: a stolen token is valid until it expires. The access token / refresh token pattern is the standard solution.

The refresh flow: when the access token expires, the client silently sends the refresh token to /auth/refresh. If the refresh token is valid and not revoked, the server issues a new access token — and optionally rotates the refresh token too. The user never sees a logout screen.

The security benefit is about blast radius. A stolen access token is valid for at most 15 minutes. A stolen refresh token is serious — but refresh tokens can be stored in httpOnly cookies, making them inaccessible to JavaScript and therefore to XSS attacks that target localStorage.

What Can Go Wrong — Security Failure Modes

Verification Code Examples

Both examples explicitly specify the allowed algorithm. This is the single most important implementation detail — never let the token header dictate the algorithm.

const jwt = require('jsonwebtoken');

// Always specify algorithms — never omit this option
function verifyToken(token) {
  try {
    const payload = jwt.verify(token, process.env.JWT_SECRET, {
      algorithms: ['HS256'],   // explicit allowlist
    });
    return { ok: true, payload };
  } catch (err) {
    return { ok: false, error: err.message };
  }
}

// Usage in Express middleware
function authMiddleware(req, res, next) {
  const header = req.headers['authorization'] ?? '';
  const token  = header.replace(/^Bearer\s+/i, '');
  const { ok, payload, error } = verifyToken(token);
  if (!ok) return res.status(401).json({ error });
  req.user = payload;
  next();
}

import jwt
import os
from datetime import datetime, timezone

SECRET = os.environ["JWT_SECRET"]

def verify_token(token: str) -> dict:
    # Always pass algorithms= explicitly — PyJWT will raise
    # DecodeError if the token uses a different algorithm
    payload = jwt.decode(
        token,
        SECRET,
        algorithms=["HS256"],   # explicit allowlist
    )
    return payload          # raises on invalid sig or expired exp

# Example — FastAPI dependency
from fastapi import Depends, HTTPException, Header

def current_user(authorization: str = Header(...)):
    scheme, _, token = authorization.partition(" ")
    if scheme.lower() != "bearer":
        raise HTTPException(status_code=401)
    try:
        return verify_token(token)
    except jwt.PyJWTError as exc:
        raise HTTPException(status_code=401, detail=str(exc))

FAQ