JWT Structure, Claims & Debugging Guide

Everything developers need to understand, implement, and debug JSON Web Tokens — from anatomy and claims to security pitfalls and production best practices.

JWT Anatomy: Header.Payload.Signature

A JWT is three Base64URL-encoded JSON objects concatenated with dots. It is not encrypted by default — the payload is readable by anyone who has the token. It is only signed, which ensures integrity (it hasn't been tampered with) but not confidentiality.

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9    ← Header
.eyJzdWIiOiJ1c2VyXzEyMyIsIm5hbWUiOiJBbGljZSIsImlhdCI6MTcwNDY3MjAwMCwiZXhwIjoxNzA0Njc1NjAwfQ==
                                           ← Payload (readable!)
.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV...   ← Signature (verifiable)

Decoded Header

{
  "alg": "RS256",   // Algorithm: RS256, HS256, ES256, PS256
  "typ": "JWT",     // Token type
  "kid": "key-1"   // Optional: Key ID for key rotation
}

Decoded Payload (Claims)

{
  // Registered Claims (RFC 7519 standard)
  "iss": "https://auth.yourapp.com",   // Issuer
  "sub": "user_123",                   // Subject (user ID)
  "aud": "api.yourapp.com",            // Audience (your API)
  "exp": 1704675600,                   // Expiry (Unix timestamp)
  "nbf": 1704672000,                   // Not Before
  "iat": 1704672000,                   // Issued At
  "jti": "a1b2c3d4-uuid",             // JWT ID (for revocation)

  // Custom Application Claims
  "email": "[email protected]",
  "roles": ["user", "admin"],
  "plan": "pro"
}

Algorithm Comparison

Node.js Implementation

Sign and Verify with jsonwebtoken

import jwt from 'jsonwebtoken';
import { readFileSync } from 'fs';

const PRIVATE_KEY = readFileSync('./keys/private.pem');
const PUBLIC_KEY = readFileSync('./keys/public.pem');

// Sign a token (RS256)
function signToken(userId: string, roles: string[]): string {
  return jwt.sign(
    {
      sub: userId,
      roles,
      iss: 'https://auth.yourapp.com',
      aud: 'api.yourapp.com',
    },
    PRIVATE_KEY,
    {
      algorithm: 'RS256',
      expiresIn: '15m',   // Short-lived access token
      jwtid: crypto.randomUUID(),
    }
  );
}

// Verify a token — always specify algorithms explicitly!
function verifyToken(token: string) {
  return jwt.verify(token, PUBLIC_KEY, {
    algorithms: ['RS256'],          // ← NEVER omit this!
    issuer: 'https://auth.yourapp.com',
    audience: 'api.yourapp.com',
  });
}

Express Middleware

import { Request, Response, NextFunction } from 'express';

export function authenticate(req: Request, res: Response, next: NextFunction) {
  const authHeader = req.headers.authorization;
  if (!authHeader?.startsWith('Bearer ')) {
    return res.status(401).json({ error: 'Missing token' });
  }

  const token = authHeader.slice(7);
  try {
    const payload = verifyToken(token);
    req.user = payload;  // Attach verified claims to request
    next();
  } catch (err) {
    if (err instanceof jwt.TokenExpiredError) {
      return res.status(401).json({ error: 'Token expired' });
    }
    return res.status(401).json({ error: 'Invalid token' });
  }
}

Python Implementation (python-jose)

from jose import jwt, JWTError
from datetime import datetime, timedelta, timezone
import uuid

SECRET_KEY = "your-256-bit-secret-from-env"
ALGORITHM = "HS256"

def create_access_token(user_id: str, roles: list[str]) -> str:
    now = datetime.now(timezone.utc)
    payload = {
        "sub": user_id,
        "roles": roles,
        "iss": "https://auth.yourapp.com",
        "aud": "api.yourapp.com",
        "iat": now,
        "exp": now + timedelta(minutes=15),
        "jti": str(uuid.uuid4()),
    }
    return jwt.encode(payload, SECRET_KEY, algorithm=ALGORITHM)

def verify_token(token: str) -> dict:
    try:
        payload = jwt.decode(
            token,
            SECRET_KEY,
            algorithms=[ALGORITHM],          # explicit allowlist
            audience="api.yourapp.com",
            issuer="https://auth.yourapp.com",
        )
        return payload
    except JWTError as e:
        raise ValueError(f"Invalid token: {e}")

Critical JWT Vulnerabilities