Auth & Security

Refresh Token Rotation & Mutex Locking

Mutex Guard

Implement bulletproof session lifecycle management using single-use Refresh Token Rotation (RTR). Protect your single-page app against token theft with automatic token family invalidation and prevent browser race conditions using client-side mutex request queuing.

Interactive Rotation & Threat Simulator

Select an operational mode to test token exchange, short-lived renewals, or simulate a token reuse breach:

Execute: Standard Token Rotation

POST

response.json

{

// Click "Send" above to execute this request against the live server.

}

Threat Model: Token Reuse Detection (RFC 6749)

How token families detect stolen refresh tokens and trigger automatic session invalidation:

Normal Token Rotation

Legitimate user exchanges Token A for Token B. The gateway consumes Token A and issues Token B with the same family ID.

Attacker Replay Attempt

An attacker who previously intercepted Token A attempts to exchange it. The server detects that Token A has already been consumed.

Total Family Revocation

The authorization gateway treats reuse as an active breach, immediately revoking Token B as well, forcing all parties to re-authenticate.

Client-Side Concurrency Mutex Pattern

When multiple concurrent API calls fail with 401 at the same instant (e.g., initial page load with 5 parallel widgets), only one refresh request must fire. All other calls wait in a pending queue:

authInterceptor.ts

// Production Axios Response Interceptor with Mutex Lock & Request Queue

import axios, { AxiosError, InternalAxiosRequestConfig } from 'axios';

export const api = axios.create({

baseURL: 'https://playground.nileslabs.com/api/v1',

});

let isRefreshing = false;

let failedQueue: Array<{

resolve: (token: string) => void;

reject: (err: any) => void;

}> = [];

const processQueue = (error: any, token: string | null = null) => {

failedQueue.forEach((prom) => {

if (error) prom.reject(error);

else if (token) prom.resolve(token);

});

failedQueue = [];

};

// Response Interceptor: Intercept 401s and queue parallel requests

api.interceptors.response.use(

(response) => response,

async (error: AxiosError) => {

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

// Detect 401 and avoid infinite retry loops

if (error.response?.status === 401 && !originalRequest._retry) {

if (isRefreshing) {

// Mutex Active: Queue this concurrent request until the token arrives

return new Promise<string>((resolve, reject) => {

failedQueue.push({ resolve, reject });

}).then((newToken) => {

originalRequest.headers.Authorization = Bearer ${newToken};

return api(originalRequest);

});

}

originalRequest._retry = true;

isRefreshing = true;

try {

const storedRefreshToken = localStorage.getItem('refresh_token');

const { data } = await axios.post('https://playground.nileslabs.com/api/v1/auth/refresh', {

refreshToken: storedRefreshToken,

});

const newAccessToken = data.access_token;

const newRefreshToken = data.refresh_token;

localStorage.setItem('access_token', newAccessToken);

localStorage.setItem('refresh_token', newRefreshToken);

// Resume all queued concurrent requests

processQueue(null, newAccessToken);

originalRequest.headers.Authorization = Bearer ${newAccessToken};

return api(originalRequest);

} catch (refreshErr) {

processQueue(refreshErr, null);

// Force redirect to login on token reuse or expired family

localStorage.clear();

window.location.href = '/login?session_expired=true';

return Promise.reject(refreshErr);

} finally {

isRefreshing = false;

}

return Promise.reject(error);

}

);

PreviousJWT Auth Flow

NextRBAC Permission Matrix