🔄 Token Refresh Strategies

The Expiry Dilemma

Token expiry is a security feature, not a bug — the shorter a token's life, the smaller the window an attacker has if they steal it. But there's a tension:

• Short-lived tokens (5–15 min) are safe but annoying — the user keeps getting logged out.
• Long-lived tokens (days or weeks) are convenient but dangerous — a stolen one grants access for a long time, and JWTs are hard to revoke.

The two-token pattern gives you both halves: a short access token for safety, and a refresh token — tracked in your database — that can be revoked the moment anything looks wrong.

The Two-Token Pattern

At login the server issues both tokens. The access token is stateless and never stored server-side; the refresh token is stored (ideally as a hash) so you can look it up and revoke it.

const jwt = require('jsonwebtoken');

function signAccessToken(user) {
  return jwt.sign({ sub: user.id, role: user.role }, process.env.JWT_ACCESS_SECRET, {
    expiresIn: '15m',
    algorithm: 'HS256',
  });
}

function signRefreshToken(user, tokenId) {
  // jti = a unique id so we can track and revoke this specific token
  return jwt.sign({ sub: user.id, jti: tokenId }, process.env.JWT_REFRESH_SECRET, {
    expiresIn: '7d',
    algorithm: 'HS256',
  });
}

The Refresh Endpoint

The /refresh route does three checks before issuing a new access token: the refresh token's signature must verify, it must still exist in the database (not revoked), and — implicitly via verify — it must not be expired.

// A stand-in store: maps a token id (jti) to its record.
// In production this is a database table or a Redis set.
const refreshStore = new Map(); // jti -> { userId, expiresAt }

app.post('/refresh', async (req, res) => {
  const { refreshToken } = req.body;
  if (!refreshToken) {
    return res.status(401).json({ message: 'Refresh token required' });
  }

  let payload;
  try {
    // 1. Verify signature + expiry.
    payload = jwt.verify(refreshToken, process.env.JWT_REFRESH_SECRET, {
      algorithms: ['HS256'],
    });
  } catch {
    return res.status(403).json({ message: 'Invalid refresh token' });
  }

  // 2. Confirm it is still active (not revoked / logged out).
  const record = refreshStore.get(payload.jti);
  if (!record) {
    return res.status(403).json({ message: 'Refresh token revoked' });
  }

  // 3. Issue a new short access token.
  const user = { id: payload.sub, role: 'user' };
  const accessToken = signAccessToken(user);
  res.json({ accessToken });
});

Refresh-Token Rotation

The basic endpoint above keeps the same refresh token alive for a week — a stolen one works the whole time. Rotation hardens this: every time a refresh token is used, it's invalidated and a brand-new one is issued. Now a stolen token is only useful until the legitimate user next refreshes.

Better still, rotation gives you theft detection. If an already-used (rotated-out) token is presented again, something is wrong — either an attacker has an old copy or the real user does. The safe response is to revoke the entire token chain and force a fresh login.

const crypto = require('crypto');

app.post('/refresh', async (req, res) => {
  const { refreshToken } = req.body;

  let payload;
  try {
    payload = jwt.verify(refreshToken, process.env.JWT_REFRESH_SECRET, {
      algorithms: ['HS256'],
    });
  } catch {
    return res.status(403).json({ message: 'Invalid refresh token' });
  }

  const record = refreshStore.get(payload.jti);

  // Reuse of a rotated-out token => probable theft. Nuke the family.
  if (!record) {
    revokeFamily(payload.sub); // remove every refresh token for this user
    return res.status(403).json({ message: 'Token reuse detected — please log in again' });
  }

  // Rotate: delete the old, mint a new refresh token.
  refreshStore.delete(payload.jti);
  const newJti = crypto.randomUUID();
  refreshStore.set(newJti, { userId: payload.sub, expiresAt: Date.now() + 7 * 864e5 });

  const user = { id: payload.sub, role: 'user' };
  res.json({
    accessToken: signAccessToken(user),
    refreshToken: signRefreshToken(user, newJti),
  });
});

Revocation & Logout

Because access tokens are stateless, "logout" can't invalidate them directly — they simply expire in a few minutes. What logout can do is delete the refresh token so no new access tokens are ever issued for that session. That's why real logout is a server call, not just clearing client storage.

// Remove one refresh token — an ordinary logout.
app.post('/logout', (req, res) => {
  const { refreshToken } = req.body;
  try {
    const { jti } = jwt.verify(refreshToken, process.env.JWT_REFRESH_SECRET, {
      algorithms: ['HS256'],
    });
    refreshStore.delete(jti); // this session can no longer refresh
  } catch {
    /* already invalid — nothing to revoke */
  }
  res.json({ message: 'Logged out' });
});

// Remove every refresh token for a user — "log out everywhere"
// and the theft response used by revokeFamily above.
function revokeFamily(userId) {
  for (const [jti, record] of refreshStore) {
    if (record.userId === userId) refreshStore.delete(jti);
  }
}

Where to Store Tokens

Storage is where most JWT security is won or lost. There is no single "correct" place — each option trades one attack surface for another. The two threats to weigh are XSS (malicious JavaScript running in your page can read anything JS can read) and CSRF (a hostile site tricks the browser into sending your cookies).

A widely recommended pattern for web apps: keep the access token in a JavaScript variable in memory (short-lived, unreachable after a refresh), and keep the refresh token in an httpOnly, Secure, SameSite cookie so no script can read it. httpOnly closes the XSS door on the long-lived token; SameSite closes most of the CSRF door.

// Setting the refresh token as a locked-down cookie at login.
res.cookie('refreshToken', refreshToken, {
  httpOnly: true,   // JavaScript cannot read it — blocks XSS theft
  secure: process.env.NODE_ENV === 'production', // HTTPS only
  sameSite: 'strict', // not sent on cross-site requests — blocks most CSRF
  maxAge: 7 * 24 * 60 * 60 * 1000, // 7 days
  path: '/refresh',   // the browser only sends it to the refresh route
});

Transparent Client Refresh

Users shouldn't see the refresh happen. The trick is an HTTP interceptor: when a request comes back 401, automatically call /refresh, get a new access token, and retry the original request once. Here it is with an axios response interceptor.

import axios from 'axios';

const api = axios.create({ baseURL: '/api', withCredentials: true });
let accessToken = null; // kept in memory only

api.interceptors.request.use((config) => {
  if (accessToken) config.headers.Authorization = `Bearer ${accessToken}`;
  return config;
});

api.interceptors.response.use(
  (response) => response,
  async (error) => {
    const original = error.config;

    // Only try to refresh once, and only on a 401.
    if (error.response?.status === 401 && !original._retried) {
      original._retried = true;
      try {
        // The refresh cookie is sent automatically (withCredentials).
        const { data } = await axios.post('/api/refresh', {}, { withCredentials: true });
        accessToken = data.accessToken;            // update in-memory token
        original.headers.Authorization = `Bearer ${accessToken}`;
        return api(original);                        // retry the original request
      } catch (refreshErr) {
        window.location.href = '/login';             // refresh failed — re-login
        return Promise.reject(refreshErr);
      }
    }
    return Promise.reject(error);
  }
);

Practice & Quiz

app.post('/logout-all', requireAuth, (req, res) => {
  revokeFamily(req.user.sub); // delete every refresh token for this user
  res.json({ message: 'Logged out on all devices' });
});

Best Practices & Pitfalls

✅ Do

• Pair a short access token (~15 min) with a longer refresh token (days–weeks)
• Track refresh tokens server-side and store them hashed
• Rotate refresh tokens on every use and revoke the family on reuse
• Make logout a server call that deletes the refresh token
• Keep the access token in memory and the refresh token in an httpOnly, Secure, SameSite cookie
• Use separate secrets for access and refresh tokens

❌ Don't

• Don't keep long-lived tokens in localStorage for real accounts
• Don't trust a refresh token on signature alone — always check the store
• Don't fire parallel refreshes; queue them behind one in-flight request
• Don't forget CSRF defence when the refresh token lives in a cookie
• Don't treat clearing client storage as a real logout

Summary

📚 Additional Resources

• OWASP — JSON Web Token Cheat Sheet
• RFC 6749 §1.5 — refresh tokens in OAuth 2.0
• jsonwebtoken — signing and verifying with separate secrets
• MDN — the SameSite cookie attribute

🚀 What's Next?

JWTs aren't the only way to keep a user logged in. The next lesson, Express Sessions, revisits the stateful, server-side approach — cookies backed by a session store — so you can choose the right tool for each app instead of reaching for tokens by reflex.