Refresh Tokens and Silent Refresh

Hey everyone, Richa here! 👋

Day 15. Last day of Week 3.

And today we're going deep on the piece that makes JWT auth actually usable in production.

Refresh tokens and silent refresh.

On Day 11 I mentioned the JWT invalidation problem — access tokens expire, and if you make them too short, users keep getting logged out. The solution is access tokens + refresh tokens + silent refresh. Today we build the whole thing.

This is one of those topics where I've seen so many wrong implementations. Tutorials that store the refresh token in localStorage. Implementations that cause infinite refresh loops. Race conditions where multiple requests all try to refresh at the same time.

Today we get it right.

Quick recap — why we need this

Access tokens are short-lived (15 minutes) so a stolen token is useless quickly.

But a 15-minute expiry means users get logged out every 15 minutes. That's not acceptable.

The solution:

Access token   → short-lived (15 min), used for every API request
Refresh token  → long-lived (7-30 days), stored securely, used ONLY to get new access tokens

When the access token expires, the app silently sends the refresh token to get a new access token — without the user having to log in again. If the refresh token is also expired (or invalidated on logout) — then the user logs in again.

The user experience: they stay logged in for weeks. Behind the scenes, their access token rotates every 15 minutes. They never see it happen.

How the full flow works

1. Login
   → Server returns:
     - Access token (HttpOnly cookie, 15 min expiry)
     - Refresh token (HttpOnly cookie, 7 day expiry)

2. Normal API call
   → Browser sends access token cookie automatically
   → Server verifies access token
   → Returns data ✅

3. Access token expires (after 15 min)
   → API call returns 401

4. Silent refresh (triggered by 401)
   → App sends POST /api/auth/refresh
   → Browser sends refresh token cookie automatically
   → Server validates refresh token (checks DB — can be invalidated)
   → Server issues new access token cookie
   → Server optionally rotates refresh token (issues new one, invalidates old)
   → App retries original request ✅

5. Logout
   → App sends POST /api/auth/logout
   → Server deletes refresh token from DB
   → Server clears both cookies
   → Refresh token is now permanently invalid

The user only notices step 1 (the login form) and step 5 (the logout button). Everything else is invisible.

The axios interceptor — handling 401s silently

We started this on Day 12. Now let's handle the edge cases properly — especially the race condition.

The race condition: if multiple API requests are in flight when the access token expires, they all get 401s at the same time. Without protection, they all try to call the refresh endpoint simultaneously — multiple refresh requests, potentially causing issues.

The fix: a refresh queue. If a refresh is already in progress, queue the other requests and resolve them all when the refresh completes.

// services/apiClient.ts
import axios, { AxiosInstance, InternalAxiosRequestConfig } from 'axios';
import { authService } from './authService';

// Track if a refresh is currently in progress
let isRefreshing = false;

// Queue of requests waiting for token refresh
let refreshQueue: Array<{
  resolve: (value?: unknown) => void;
  reject: (reason?: unknown) => void;
}> = [];

// Process all queued requests after refresh
function processQueue(error: Error | null) {
  refreshQueue.forEach(({ resolve, reject }) => {
    if (error) {
      reject(error);
    } else {
      resolve();
    }
  });
  refreshQueue = [];
}

export const apiClient: AxiosInstance = axios.create({
  baseURL: '/api',
  withCredentials: true, // sends cookies automatically
});

apiClient.interceptors.response.use(
  (response) => response, // success — pass through

  async (error) => {
    const originalRequest = error.config as InternalAxiosRequestConfig & { _retry?: boolean };

    // Only handle 401s, and only if we haven't already retried this request
    if (error.response?.status !== 401 || originalRequest._retry) {
      return Promise.reject(error);
    }

    // Don't try to refresh if the refresh endpoint itself returned 401
    if (originalRequest.url?.includes('/auth/refresh')) {
      // Refresh failed — clear auth state and redirect to login
      window.location.href = '/login';
      return Promise.reject(error);
    }

    originalRequest._retry = true;

    // If a refresh is already happening — queue this request
    if (isRefreshing) {
      return new Promise((resolve, reject) => {
        refreshQueue.push({ resolve, reject });
      }).then(() => apiClient(originalRequest))
        .catch((err) => Promise.reject(err));
    }

    // Start the refresh
    isRefreshing = true;

    try {
      await authService.refreshToken(); // POST /api/auth/refresh
      processQueue(null);               // resume all queued requests
      return apiClient(originalRequest); // retry the request that triggered this
    } catch (refreshError) {
      processQueue(refreshError as Error); // fail all queued requests
      window.location.href = '/login';
      return Promise.reject(refreshError);
    } finally {
      isRefreshing = false;
    }
  }
);

With the queue in place:

Request A gets 401 → starts refresh → isRefreshing = true
Request B gets 401 → sees isRefreshing → queued
Request C gets 401 → queued
Refresh completes → processQueue(null) → B and C are retried
All three requests complete successfully
User never saw a single error

Refresh token rotation — why you should do it

Basic refresh token: one refresh token, used forever until it expires.

Refresh token rotation: every time you use a refresh token, the server issues a new one and invalidates the old one.

First refresh:
  Send old refresh token → get new access token + new refresh token
  Old refresh token is now invalid

Second refresh:
  Send new refresh token → get new access token + newer refresh token
  Previous refresh token is now invalid

Why this matters: if a refresh token is stolen, the attacker uses it once to get an access token. That use rotates the token. When your app tries to use the original refresh token next time — it's been invalidated. The server can detect the reuse and invalidate the whole session.

It's not foolproof — but it limits the attack window significantly and gives you a detection mechanism.

Implement this on the server side. The client-side code doesn't change — it just sends whatever refresh token it has.

Proactive refresh — refreshing before expiry

The reactive approach (refresh on 401) works but has one minor issue: the user's request fails and has to be retried. For most apps this is fine — it's invisible. But for some use cases (file uploads, real-time operations) you want to avoid the 401 altogether.

The proactive approach: check the token expiry and refresh before it happens.

// utils/tokenUtils.ts

// Decode JWT payload (remember — not secure, just for reading expiry)
function getTokenExpiry(token: string): number | null {
  try {
    const payload = JSON.parse(atob(token.split('.')[1]));
    return payload.exp ?? null;
  } catch {
    return null;
  }
}

function isTokenExpiringSoon(token: string, bufferSeconds = 60): boolean {
  const exp = getTokenExpiry(token);
  if (!exp) return true;
  const now = Math.floor(Date.now() / 1000);
  return exp - now < bufferSeconds; // refresh if expiring within 60 seconds
}

// hooks/useTokenRefresh.ts
import { useEffect, useRef } from 'react';
import { authService } from '../services/authService';
import { useAuthContext } from '../context/AuthContext';

export function useTokenRefresh() {
  const { isAuthenticated, logout } = useAuthContext();
  const intervalRef = useRef<ReturnType<typeof setInterval>>();

  useEffect(() => {
    if (!isAuthenticated) return;

    // Check every minute if the token needs refreshing
    intervalRef.current = setInterval(async () => {
      try {
        await authService.refreshToken();
      } catch {
        // Refresh failed — session is over
        await logout();
      }
    }, 1000 * 60 * 14); // every 14 minutes (access token is 15 min)

    return () => {
      if (intervalRef.current) clearInterval(intervalRef.current);
    };
  }, [isAuthenticated, logout]);
}

Use it in the root layout:

function AppLayout() {
  useTokenRefresh(); // silently refreshes every 14 minutes
  return <Outlet />;
}

Choose the approach that fits your app:

Reactive (401 interceptor) — simpler, works for most apps, tiny retry delay
Proactive (interval) — no retry delay, better for real-time or upload-heavy apps

Many production apps use both — the interval for routine refresh, and the interceptor as a safety net.

The complete security picture — putting it all together

Here's what the full auth security model looks like with everything from this week:

Storage
  Access token   → HttpOnly cookie (JS can't read it)
  Refresh token  → HttpOnly cookie, separate (JS can't read it)

Protection
  Both cookies   → Secure flag (HTTPS only)
  Both cookies   → SameSite=Strict (no CSRF)
  Access token   → 15 min expiry (stolen token useless quickly)
  Refresh token  → DB-backed (can be invalidated on logout)
  Refresh token  → Rotated on use (stolen token detected on reuse)

React
  getMe()        → on mount (session survives refreshes)
  isLoading      → true until session check done (no flash)
  401 interceptor → silent refresh + request queue (race condition safe)
  Proactive refresh → every 14 min (avoids failed requests)

This is the same pattern you'd find in a well-built fintech or SaaS app. It's not overkill — it's just correct.

Week 3 wrap-up

This week we covered:

Day 11 — JWT vs sessions vs cookies: the concepts most tutorials get wrong
Day 12 — Building the auth flow: authService, apiClient, useAuth hook
Day 13 — Protected routes: no flash, role-based access, redirect-back after login
Day 14 — Auth context: the full AuthProvider that ties it all together
Day 15 — Refresh tokens and silent refresh: the race condition fix and rotation