JWT Token Refresh Patterns in React 19: Avoiding the Silent Auth Death Spiral

I've watched authentication break in production more times than I want to admit. Usually it's silent—users get logged out mid-action, requests fail with 401s, and nobody notices until support tickets pile up. The culprit? Naive token refresh logic that doesn't handle concurrent requests.

Most solutions I see are either bloated (Redux middleware with retry queues) or fragile (localStorage checks that fail when two requests hit simultaneously). I'm going to show you the approach I use in CitizenApp: minimal, correct, and battle-tested with concurrent traffic.

The Problem: Why Simple Token Refresh Fails

Let me paint a scenario. User opens your app. Token expires. They click a button that triggers three API calls simultaneously. Here's what happens with naive refresh:

// ❌ Bad: Each request independently tries to refresh
async function apiCall(endpoint: string) {
  let token = localStorage.getItem('token');

  const res = await fetch(endpoint, {
    headers: { Authorization: `Bearer ${token}` }
  });

  if (res.status === 401) {
    // All three requests do this at the same time
    const refreshRes = await fetch('/api/auth/refresh', {
      method: 'POST',
      body: JSON.stringify({ refreshToken: localStorage.getItem('refreshToken') })
    });
    // ...
  }
}

You just sent three simultaneous refresh requests. Your backend probably revoked all but one token for security reasons. Congrats, now all three requests fail with 401 again, and you're in a retry loop. This is the "silent auth death spiral."

The Solution: React Context + AbortController

I prefer React Context for this over Redux because:

It's built into React—no external dependency
Token refresh is genuinely app-level state, not domain state
It's easier to reason about with AbortControllers for request queuing

Here's the implementation I use:

// auth.context.tsx
import React, { createContext, useCallback, useRef, useEffect } from 'react';

interface AuthContextType {
  token: string | null;
  refreshToken: string | null;
  setTokens: (token: string, refreshToken: string) => void;
  clearTokens: () => void;
  getValidToken: () => Promise<string>;
}

export const AuthContext = createContext<AuthContextType | null>(null);

export function AuthProvider({ children }: { children: React.ReactNode }) {
  const [token, setToken] = React.useState<string | null>(null);
  const [refreshToken, setRefreshToken] = React.useState<string | null>(null);
  const refreshPromiseRef = useRef<Promise<string> | null>(null);
  const abortControllerRef = useRef<AbortController | null>(null);

  // Load tokens from secure storage on mount
  useEffect(() => {
    const token = sessionStorage.getItem('token');
    const refreshToken = sessionStorage.getItem('refreshToken');
    if (token && refreshToken) {
      setToken(token);
      setRefreshToken(refreshToken);
    }
  }, []);

  const performRefresh = useCallback(
    async (refreshTokenValue: string): Promise<string> => {
      // Cancel previous refresh attempt if still in flight
      if (abortControllerRef.current) {
        abortControllerRef.current.abort();
      }

      abortControllerRef.current = new AbortController();

      try {
        const res = await fetch('/api/auth/refresh', {
          method: 'POST',
          headers: { 'Content-Type': 'application/json' },
          body: JSON.stringify({ refreshToken: refreshTokenValue }),
          signal: abortControllerRef.current.signal
        });

        if (res.status === 401 || res.status === 403) {
          // Refresh token expired—user must re-login
          clearTokens();
          throw new Error('Refresh token expired');
        }

        if (!res.ok) {
          throw new Error(`Refresh failed: ${res.statusText}`);
        }

        const { token: newToken, refreshToken: newRefreshToken } = await res.json();
        setToken(newToken);
        setRefreshToken(newRefreshToken);
        sessionStorage.setItem('token', newToken);
        sessionStorage.setItem('refreshToken', newRefreshToken);

        return newToken;
      } catch (error) {
        if (error instanceof Error && error.name === 'AbortError') {
          throw new Error('Refresh cancelled');
        }
        throw error;
      }
    },
    []
  );

  const getValidToken = useCallback(async (): Promise<string> => {
    // If we already have a refresh in flight, wait for it
    if (refreshPromiseRef.current) {
      return refreshPromiseRef.current;
    }

    // If token exists and isn't expired, return it
    if (token && !isTokenExpired(token)) {
      return token;
    }

    // Otherwise, start a refresh
    if (!refreshToken) {
      throw new Error('No refresh token available');
    }

    refreshPromiseRef.current = performRefresh(refreshToken)
      .finally(() => {
        refreshPromiseRef.current = null;
      });

    return refreshPromiseRef.current;
  }, [token, refreshToken, performRefresh]);

  return (
    <AuthContext.Provider
      value={{
        token,
        refreshToken,
        setTokens: (t, rt) => {
          setToken(t);
          setRefreshToken(rt);
          sessionStorage.setItem('token', t);
          sessionStorage.setItem('refreshToken', rt);
        },
        clearTokens: () => {
          setToken(null);
          setRefreshToken(null);
          sessionStorage.clear();
        },
        getValidToken
      }}
    >
      {children}
    </AuthContext.Provider>
  );
}

function isTokenExpired(token: string): boolean {
  try {
    const payload = JSON.parse(atob(token.split('.')[1]));
    return payload.exp * 1000 < Date.now();
  } catch {
    return true;
  }
}

Now your fetch interceptor:

// api.ts
import { AuthContext } from './auth.context';

export function useApi() {
  const authContext = React.useContext(AuthContext);

  return useCallback(
    async (endpoint: string, options: RequestInit = {}) => {
      if (!authContext) throw new Error('AuthProvider not found');

      try {
        const token = await authContext.getValidToken();
        const headers = new Headers(options.headers || {});
        headers.set('Authorization', `Bearer ${token}`);

        let res = await fetch(endpoint, { ...options, headers });

        // If still 401 after refresh attempt, we're truly unauthorized
        if (res.status === 401) {
          authContext.clearTokens();
          window.location.href = '/login';
          throw new Error('Session expired');
        }

        return res;
      } catch (error) {
        if (error instanceof Error && error.message === 'No refresh token available') {
          window.location.href = '/login';
        }
        throw error;
      }
    },
    [authContext]
  );
}

Why This Works

Concurrency handling: The refreshPromiseRef ensures only one refresh happens at a time. Multiple concurrent requests wait for the same promise.

// Three requests hit simultaneously
await Promise.all([
  useApi()('/api/users'),
  useApi()('/api/posts'),
  useApi()('/api/notifications')
]);
// All three call getValidToken() → same refresh promise → single refresh request

AbortController prevents stale refreshes: If a user navigates away or a component unmounts mid-refresh, we abort the request instead of updating state on an unmounted component.

Session storage, not localStorage: Tokens should die with the browser tab. I never use localStorage for auth—it survives XSS attacks longer than it should.

The FastAPI Backend

Keep it simple:

# auth.py
from fastapi import HTTPException, status
from jose import JWTError, jwt
from datetime import datetime, timedelta

SECRET = "your-secret"

def create_tokens(user_id: str):
    access_payload = {
        'sub': user_id,
        'exp': datetime.utcnow() + timedelta(minutes=15),
        'type': 'access'
    }
    refresh_payload = {
        'sub': user_id,
        'exp': datetime.utcnow() + timedelta(days=7),
        'type': 'refresh'
    }
    return {
        'token': jwt.encode(access_payload, SECRET),
        'refreshToken': jwt.encode(refresh_payload, SECRET)
    }

@app.post('/api/auth/refresh')
async def refresh(data: dict):
    try:
        payload = jwt.decode(data['refreshToken'], SECRET, algorithms=['HS256'])
        if payload.get('type') != 'refresh':
            raise HTTPException(status_code=401)
        return create_tokens(payload['sub'])
    except JWTError:
        raise HTTPException(status_code=403)

Gotcha: Token Expiration Skew

This burned me: I assumed isTokenExpired() would perfectly predict when a token fails. It doesn't. Clock skew between client and server, plus network latency, means a token can appear valid client-side but fail server-side by milliseconds.

Fix: Add a 30-second buffer:

function isTokenExpired(token: string, bufferSeconds = 30): boolean {
  try {
    const payload = JSON.parse(atob(token.split('.')[1]));
    return payload.exp * 1000 < Date.now() + bufferSeconds * 1000;
  } catch {
    return true;
  }
}

This makes the client refresh slightly early, avoiding the 401 entirely on most requests.

JWT Token Refresh Patterns in React 19: Avoiding the Silent Auth Death Spiral

JWT Token Refresh Patterns in React 19: Avoiding the Silent Auth Death Spiral

The Problem: Why Simple Token Refresh Fails

The Solution: React Context + AbortController

Why This Works

The FastAPI Backend

Gotcha: Token Expiration Skew

What I

Tags

Author

Stats

Published

You Might Also Like

Astro + React 19 Islands: Shipping Zero JavaScript Until User Interaction—The CitizenApp Case Study

Streaming AI Responses in React 19: Building Real-Time Claude Integration Without the UX Jank

Tailwind CSS Component Slots in React 19: Building Flexible, Reusable UI Without Prop Drilling Hell

Building Dynamic RBAC in React 19: From Permission Strings to Component-Level Access Control

What useOptimistic Actually Saves You