JWT Authentication
Deep Dive

What Is a JWT?

A JSON Web Token is a compact, self-contained string that carries information about a user or system in a format that can be independently verified. The key word is self-contained: unlike session cookies that require a database lookup on every request, a JWT encodes the user's identity and permissions directly inside the token — and proves they haven't been altered using a cryptographic signature.

When a user logs in, your server creates a JWT signed with a secret key (or private key) and sends it back. On every subsequent request, the client includes that token. The server verifies the signature — without touching a database — and trusts the claims inside. This makes JWTs particularly attractive for stateless architectures, APIs, and microservices where you want to avoid session storage.

The trade-off: JWTs can't be invalidated before they expire. If you issue a token and the user logs out or their permissions change, the token is still technically valid until its expiry. Managing this is the central challenge of JWT-based auth systems.

JWT Structure in Detail

Every JWT is three Base64URL-encoded JSON objects joined by dots. Understanding what lives in each part — and what the limitations are — is fundamental to implementing JWTs correctly.

Signing Algorithms Compared

The algorithm you choose affects your security model, your infrastructure requirements, and what attack surface you expose. There are two families worth understanding.

The Full Token Lifecycle

Understanding the end-to-end lifecycle — from user login to token expiry — helps you design auth flows that are both secure and usable.

POST /auth/login  →  { username, password }

{ access_token: "eyJ...", refresh_token: "...", expires_in: 900 }

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

verify(token, secret, { algorithms: ['HS256'], audience: 'api.myapp.com' })

POST /auth/refresh  →  { refresh_token: "..." }

Server-Side Validation: Every Check That Matters

Receiving a JWT is not the same as trusting it. Validation is not one step — it's a sequence of checks, each of which can independently fail. Skip one and you may have a security hole.

// ❌ Wrong — doesn't verify signature
const payload = jwt.decode(token);

// ✅ Correct — throws if signature invalid
const payload = jwt.verify(token, secret);

jwt.verify(token, secret, { algorithms: ['HS256'] });

jwt.verify(token, secret, { clockTolerance: 30 });

jwt.verify(token, secret, { audience: 'api.myapp.com' });

jwt.verify(token, secret, { issuer: 'https://auth.myapp.com' });

const isRevoked = await tokenBlocklist.has(payload.jti);
if (isRevoked) throw new Error('Token revoked');

Refresh Tokens and Rotation

Access tokens are intentionally short-lived — typically 15 minutes to one hour. This limits the damage if a token is stolen: it expires quickly. But you don't want to force users to log in every 15 minutes. That's where refresh tokens come in.

A refresh token is a longer-lived credential (days to weeks) that can be exchanged for a new access token without requiring the user's password again. It's stored more securely than the access token and is only sent to the auth server — never to regular API endpoints.

Refresh token rotation

The security-conscious pattern is refresh token rotation: every time a refresh token is used, it's immediately invalidated and a new one is issued. This enables detection of token theft: if an attacker and the legitimate user both try to use copies of the same refresh token, the second use will fail — and you can invalidate the entire token family, logging the user out everywhere.

Token revocation strategies

Where to Store JWTs

Token storage is one of the most debated topics in JWT security — and the right answer depends on your threat model. Here are the three common options and their trade-offs.

Security Mistakes to Avoid

Implementation Patterns

A few concrete patterns that handle the most common scenarios correctly.

import jwt from 'jsonwebtoken';
import crypto from 'crypto';

async function login(userId, userRole) {
  // Short-lived access token
  const accessToken = jwt.sign(
    { sub: userId, role: userRole },
    process.env.JWT_SECRET,
    {
      algorithm: 'HS256',
      expiresIn: '15m',
      audience: 'api.myapp.com',
      issuer: 'https://auth.myapp.com',
      jwtid: crypto.randomUUID(),
    }
  );

  // Longer-lived refresh token (opaque, stored in DB)
  const refreshToken = crypto.randomBytes(32).toString('hex');
  await db.storeRefreshToken(userId, refreshToken, '7d');

  return { accessToken, refreshToken };
}

function authMiddleware(req, res, next) {
  const header = req.headers.authorization;
  if (!header?.startsWith('Bearer ')) {
    return res.status(401).json({ error: 'Missing token' });
  }

  const token = header.slice(7);
  try {
    const payload = jwt.verify(token, process.env.JWT_SECRET, {
      algorithms: ['HS256'],      // explicit allowlist
      audience: 'api.myapp.com', // validate audience
      issuer: 'https://auth.myapp.com',
      clockTolerance: 30,         // 30s clock skew tolerance
    });
    req.user = payload;
    next();
  } catch (err) {
    return res.status(401).json({ error: 'Invalid or expired token' });
  }
}

async function refreshTokens(oldRefreshToken) {
  const stored = await db.getRefreshToken(oldRefreshToken);

  if (!stored || stored.usedAt) {
    // Possible replay — revoke entire token family
    if (stored?.userId) {
      await db.revokeAllUserTokens(stored.userId);
    }
    throw new Error('Refresh token invalid or already used');
  }

  // Mark old token as used immediately
  await db.markRefreshTokenUsed(oldRefreshToken);

  // Issue new token pair
  return login(stored.userId, stored.userRole);
}

JWT Security Checklist

Run through this before shipping any JWT-based authentication flow.