JWT (JSON Web Tokens) Complete Guide 2026: Authentication Explained from Scratch

// A JWT (access token, shortened for readability)
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9
  .eyJzdWIiOiJ1c2VyXzEyMyIsInJvbGUiOiJhZG1pbiIsImlhdCI6MTcxNjAwMDAwMCwiZXhwIjoxNzE2MDAwOTAwfQ
  .SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

// ── PART 1: Header ────────────────────────────────────────────────────────
{
  "alg": "HS256",    // Signing algorithm — HMAC-SHA256
  "typ": "JWT"       // Token type
}

// ── PART 2: Payload (Claims) ──────────────────────────────────────────────
{
  "sub": "user_123",         // Subject — who this token represents
  "role": "admin",           // Custom claim — your business data
  "plan": "pro",             // Custom claim — subscription tier
  "iat": 1716000000,         // Issued At — Unix seconds
  "exp": 1716000900,         // Expires At — exactly 15 minutes later
  "iss": "api.myapp.com"    // Issuer — who created this token
}

// ── PART 3: Signature ─────────────────────────────────────────────────────
// HMACSHA256(
//   base64url(header) + "." + base64url(payload),
//   SECRET_KEY
// )
// If header or payload changes by even 1 bit → signature mismatch → rejected

import jwt from 'jsonwebtoken';
import { randomBytes } from 'crypto';

const ACCESS_SECRET  = process.env.JWT_ACCESS_SECRET;   // 256-bit random string
const REFRESH_SECRET = process.env.JWT_REFRESH_SECRET;  // DIFFERENT secret from access

// ── Sign — called on successful login ─────────────────────────────────────
function signTokens(userId, role) {
  const accessToken = jwt.sign(
    { sub: userId, role, type: 'access' },
    ACCESS_SECRET,
    { expiresIn: '15m', issuer: 'api.myapp.com' }
  );

  const refreshToken = jwt.sign(
    {
      sub: userId,
      type: 'refresh',
      jti: randomBytes(16).toString('hex'), // unique ID for revocation
    },
    REFRESH_SECRET,
    { expiresIn: '7d', issuer: 'api.myapp.com' }
  );

  return { accessToken, refreshToken };
}

// ── Middleware — runs on every protected route ─────────────────────────────
function requireAuth(req, res, next) {
  const header = req.headers.authorization;
  if (!header?.startsWith('Bearer ')) {
    return res.status(401).json({ error: 'Missing token', code: 'NO_TOKEN' });
  }

  try {
    const payload = jwt.verify(header.slice(7), ACCESS_SECRET, {
      issuer: 'api.myapp.com',
      // jwt.verify throws automatically on: expired, bad signature, wrong issuer
    });

    if (payload.type !== 'access') {
      return res.status(401).json({ error: 'Wrong token type', code: 'WRONG_TYPE' });
    }

    req.user = { id: payload.sub, role: payload.role };
    next();
  } catch (err) {
    const code = err.name === 'TokenExpiredError' ? 'TOKEN_EXPIRED' : 'INVALID_TOKEN';
    return res.status(401).json({ error: err.message, code });
  }
}

// ── Refresh endpoint — POST /auth/refresh ─────────────────────────────────
async function refreshHandler(req, res) {
  const refreshToken = req.cookies.refreshToken; // HttpOnly cookie, auto-sent
  if (!refreshToken) return res.status(401).json({ error: 'No refresh token' });

  try {
    const payload = jwt.verify(refreshToken, REFRESH_SECRET, {
      issuer: 'api.myapp.com',
    });

    // Check revocation (Redis) — catches stolen refresh tokens that were already used
    const isRevoked = await redis.get(`revoked:${payload.jti}`);
    if (isRevoked) {
      return res.status(401).json({ error: 'Refresh token revoked', code: 'REVOKED' });
    }

    // Rotate: invalidate old refresh token, issue new one (refresh token rotation)
    await redis.set(`revoked:${payload.jti}`, '1', 'EX', 7 * 86400);

    const { accessToken, refreshToken: newRefreshToken } = signTokens(
      payload.sub,
      await getUserRole(payload.sub)
    );

    // Set new refresh token cookie
    res.cookie('refreshToken', newRefreshToken, {
      httpOnly: true,
      secure: true,
      sameSite: 'strict',
      maxAge: 7 * 24 * 60 * 60 * 1000,
    });

    res.json({ accessToken });
  } catch {
    res.status(401).json({ error: 'Invalid refresh token', code: 'INVALID_REFRESH' });
  }
}

import { useCallback, useRef } from 'react';

// Drop-in replacement for fetch() — handles token injection and auto-refresh
export function useAuthFetch() {
  const tokenRef = useRef<string | null>(null);

  const authFetch = useCallback(async (url: string, init: RequestInit = {}) => {
    const headers = new Headers(init.headers);

    if (tokenRef.current) {
      headers.set('Authorization', `Bearer ${tokenRef.current}`);
    }

    let res = await fetch(url, { ...init, headers });

    // On token expiry — silently refresh and retry once
    if (res.status === 401) {
      const body = await res.clone().json().catch(() => ({}));

      if (body.code === 'TOKEN_EXPIRED') {
        const refreshRes = await fetch('/api/auth/refresh', {
          method: 'POST',
          credentials: 'include', // sends the HttpOnly refresh cookie automatically
        });

        if (refreshRes.ok) {
          const { accessToken } = await refreshRes.json();
          tokenRef.current = accessToken;
          headers.set('Authorization', `Bearer ${accessToken}`);
          res = await fetch(url, { ...init, headers }); // retry original request
        }
      }
    }

    return res;
  }, []);

  return {
    authFetch,
    setToken:   (token: string) => { tokenRef.current = token; },
    clearToken: ()              => { tokenRef.current = null;  },
  };
}

// Usage in a component:
// const { authFetch, setToken } = useAuthFetch();
// setToken(accessTokenFromLogin);
// const data = await authFetch('/api/profile').then(r => r.json());