Next.js 16: What Is the Best Approach for JWT Refresh Token Rotation?

[ahmedhammami-dev]

Summary

I'm looking for advice on the recommended approach for JWT refresh-token rotation in Next.js 16.

My setup is:

• Next.js 16 App Router
• Separate backend API
• Short-lived JWT access tokens
• Rotating refresh tokens
• HTTP-only cookies

The backend handles refresh-token rotation:

R1 → refresh request → A2 + R2

R2 then becomes the new valid refresh token.

My main question is:

What is the best approach in Next.js for handling the refresh flow and setting the new HTTP-only cookie?

Should this be handled with:

• Proxy/Middleware?
• Route Handlers?
• Server Actions?
• A combination of them?

More specifically, which approach should be responsible for:

• Detecting an expired access token
• Calling the backend refresh endpoint
• Rotating the refresh token
• Setting the new HTTP-only cookie
• Retrying the original request

And how should this work when authenticated requests come from Server Components, Server Actions, and client-side navigation?

I'm also interested in how the recommended approach handles concurrent requests with rotating refresh tokens.

What is the recommended production architecture for this setup in Next.js 16?

Additional information

No response

Example

No response

[sam-wilkie]

Short version: make proxy.ts the single place that refreshes, and keep everything else read-only.

Why proxy.ts

• Server Components can't set cookies. cookies() is read-only during render, so a Server Component that finds an expired access token has no way to persist A2/R2.
• Server Actions and Route Handlers can set cookies, but only for their own request. If you refresh there, you need the same logic in three places, and page renders still can't do it.
• proxy.ts runs before every matched request (page navigations, RSC fetches from client-side navigation, Server Actions, Route Handlers). In Next.js 16 it always runs on the Node.js runtime, so you can call your backend normally.

Responsibilities

Task	Where
Detect expired/near-expiry access token	proxy.ts (decode the exp claim; no signature check needed, the backend verifies)
Call the backend refresh endpoint	proxy.ts
Set the new HTTP-only cookies	proxy.ts, on the response
Make the new token visible to the current request	proxy.ts, by rewriting the forwarded request cookies
Retry	Not needed: refresh happens before the request reaches your code
Server Components / Actions / Route Handlers	Only read the access token from cookies() and call the API

Refresh proactively (for example when exp is less than 60s away) instead of waiting for a 401. Then there's nothing to retry in the normal case.

Sketch

// proxy.ts
import { NextResponse, type NextRequest } from 'next/server'

const ACCESS = 'access_token'
const REFRESH = 'refresh_token'

function expiresSoon(jwt: string | undefined, skewSeconds = 60) {
  if (!jwt) return true
  try {
    const payload = JSON.parse(atob(jwt.split('.')[1].replace(/-/g, '+').replace(/_/g, '/')))
    return payload.exp * 1000 - Date.now() < skewSeconds * 1000
  } catch {
    return true
  }
}

export async function proxy(request: NextRequest) {
  const access = request.cookies.get(ACCESS)?.value
  const refresh = request.cookies.get(REFRESH)?.value

  if (!refresh || !expiresSoon(access)) return NextResponse.next()

  const res = await fetch(`${process.env.API_URL}/auth/refresh`, {
    method: 'POST',
    headers: { 'content-type': 'application/json' },
    body: JSON.stringify({ refreshToken: refresh }),
  })

  if (!res.ok) {
    // Refresh token invalid or reused: clear session and send to login
    const out = NextResponse.redirect(new URL('/login', request.url))
    out.cookies.delete(ACCESS)
    out.cookies.delete(REFRESH)
    return out
  }

  const { accessToken, refreshToken } = await res.json()

  // 1. Forward the new tokens to THIS request, so Server Components /
  //    Actions / Route Handlers see A2 via cookies() right away
  request.cookies.set(ACCESS, accessToken)
  request.cookies.set(REFRESH, refreshToken)
  const out = NextResponse.next({ request: { headers: request.headers } })

  // 2. Persist them in the browser
  const base = { httpOnly: true, secure: true, sameSite: 'lax' as const, path: '/' }
  out.cookies.set(ACCESS, accessToken, base)
  out.cookies.set(REFRESH, refreshToken, base)
  return out
}

export const config = {
  matcher: ['/((?!_next/static|_next/image|favicon.ico|login).*)'],
}

Step 1 is the part people usually miss: setting cookies on the response alone only affects the next request. Without rewriting the forwarded request, the Server Components rendering right now still see the expired A1.

Concurrent requests (the hard part)

With strict rotation, two parallel requests can both send R1. The first gets R2, the second hits a "reused" R1 and, if your backend does reuse detection, kills the whole session. Common in practice: client navigation fires several RSC requests at once, and prefetching makes it worse.

You can't fully fix this in Next.js alone, because requests may hit different server instances. Layered approach:

1. Backend grace window (the real fix): accept the previous refresh token for a few seconds after rotation and return the same A2/R2 it already issued. Only treat R1 as reuse after that window. Auth0, Okta and most IdPs with rotation do exactly this ("reuse interval" / "leeway").
2. Dedupe per instance in proxy.ts: keep a Map<refreshToken, Promise<tokens>> so concurrent requests on the same server share one refresh call. Delete the entry once the promise settles. This cuts most collisions but doesn't replace step 1.
3. Refresh early (the 60s skew above), so most requests never race at the expiry edge.

Client Components

Don't call your backend directly with the token from the browser (the cookie is HTTP-only anyway). Go through a Server Action or a Route Handler; both pass through proxy.ts, so they get the refresh for free.

Docs: proxy.ts cookies, cookies() behavior, middleware renamed to proxy in v16.

[DYNOSuprovo]

In Next.js App Router with rotating refresh tokens and HTTP-only cookies, the recommended architecture handles the following critical considerations:

1. Where to Refresh

• Route Handlers / Server Actions: The most reliable place to perform token refreshes. Server Actions and Route Handlers have full read and write access to cookies() (cookies().set(...)).
• Middleware: Middleware can inspect and forward tokens, but handling rotating refresh tokens inside Middleware can trigger race conditions if multiple asset/data requests fire concurrently.

2. Preventing Multi-Tab Concurrency Race Conditions

When using rotating refresh tokens (R1 -> R2):

• Backend Grace Period: Configure your authentication backend to allow a short grace window (e.g. 10–30 seconds) where the previous refresh token R1 is still accepted if another concurrent request already rotated it to R2.
• Mutex / In-Flight Promise: In your Next.js API client, track in-flight refresh promises so concurrent requests share a single refresh call rather than firing duplicate rotations.

3. Server Component Pattern

In Server Components, cookies() is read-only. Forward the current accessToken from the cookie to your backend client. If a 401 occurs in a Server Component, redirect to login or trigger a refresh via a Route Handler.

Hope this helps! If this resolves your question, please feel free to mark this as the accepted answer.

[delt4-haze]

In Next.js 16 App Router with an external API and HTTP-only cookies, the recommended approach separates concerns to avoid race conditions and invalid cookie writes:

1. Refresh logic in Route Handlers or Server Actions:
   Since Server Components are read-only for cookies during render, handle token updates inside Route Handlers or Server Actions where cookies().set() is available.

// app/api/auth/refresh/route.ts
import { cookies } from 'next/headers';
import { NextResponse } from 'next/server';

export async function POST() {
  const cookieStore = await cookies();
  const refreshToken = cookieStore.get('refreshToken')?.value;

  if (!refreshToken) {
    return NextResponse.json({ error: 'No refresh token' }, { status: 401 });
  }

  const res = await fetch('[https://api.yourbackend.com/auth/refresh](https://api.yourbackend.com/auth/refresh)', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ refreshToken }),
  });

  if (!res.ok) {
    cookieStore.delete('accessToken');
    cookieStore.delete('refreshToken');
    return NextResponse.json({ error: 'Session expired' }, { status: 401 });
  }

  const { accessToken, refreshToken: newRefreshToken } = await res.json();

  cookieStore.set('accessToken', accessToken, { httpOnly: true, secure: true, sameSite: 'lax' });
  cookieStore.set('refreshToken', newRefreshToken, { httpOnly: true, secure: true, sameSite: 'lax' });

  return NextResponse.json({ success: true, accessToken });
}


Handling Concurrent Requests:
​Backend Grace Window: Ensure your backend API allows a 10-30 second grace window for rotated tokens so parallel RSC/page requests don't instantly fail

​Middleware Scope: Use Middleware solely to inspect tokens and redirect unauthenticated users to /login, leaving actual rotation logic to API routes or Server Actions

[tisankanj]

For this setup, I would use a server-side session/BFF, with a stable opaque session ID in the browser cookie and the access/refresh tokens in a shared server-side store. That is an architectural recommendation, rather than a Next.js requirement, but it addresses the Server Component and concurrency problems together.

The distinction is rotating the backend token does not have to mean rotating the browser cookie. A Server Component can read the session ID, call a server-only API service, and have that service refresh the backend tokens in the store. It does not need to call cookies().set() during rendering. Login, logout and session-ID renewal still belong in a Server Action or Route Handler where the browser response can set cookies.

I would split the responsibilities like this:

• Proxy: optional, inexpensive checks and redirects. Keep authorization checks near the data/API. The Next.js auth guide explicitly notes that Proxy also runs for prefetched routes and recommends avoiding database checks there. I would not make every matched navigation/prefetch an independent refresh owner.
• Shared server-only API service: resolve and validate the session, check token expiry, coordinate refresh, then call NestJS. Server Components and Server Actions call this service directly. Client Components call a Route Handler/Server Action that uses the same service. A Server Component should not fetch its own /api/refresh and expect that internal response's Set-Cookie to reach the browser.
• NestJS: remains the authority for token validation, rotation, revocation and replay detection.

For parallel requests, use coordination across instances, keyed by session ID. A process-local promise map alone is insufficient. The sequence should be: acquire coordination → re-read the session record → refresh only if it is still needed → atomically persist the new token pair/version → release. Waiting requests then use the stored result. Account for lock expiry and a worker failing after NestJS rotates but before the new pair is saved; a lock by itself cannot make that cross-service operation atomic. Any retry/grace policy must be explicitly supported by the backend, bounded, and preserve replay detection.

Retry an API request at most once after a confirmed expiry; only replay mutations if the backend contract guarantees the first attempt did not execute, or you have an idempotency key. Treat timeouts, 429 and 5xx differently from confirmed invalid/revoked refresh tokens—an API outage should not delete every user's session.

The cost is a shared session store and an extra lookup. Protect tokens at rest, expire/revoke sessions, use a Secure/HttpOnly cookie in production, and protect cookie-authenticated mutations against CSRF. If you must keep the rotating tokens in browser cookies instead, Route Handlers/Actions can write them, but you still need to design how a page render reaches that browser-visible refresh response and how parallel rotations are coordinated.

References: Next.js authentication guide, cookie write restrictions, and BFF guide.

A useful verification is to expire the access token, trigger two navigations/tabs simultaneously against two app instances, and confirm one effective rotation, both requests succeeding, and no token appearing in client JSON or logs.

[sgandymov]

For Next.js 16 App Router + a separate backend, a clean approach is:

• Keep the access token short-lived.
• Store the refresh token in an HTTP-only, Secure cookie.
• Let the backend handle refresh-token rotation: R1 → A2 + R2, and invalidate R1.
• Use a Next.js Route Handler as a thin proxy to forward refresh requests and set the new refresh cookie.
• On 401, refresh once and retry the original request.
• Handle concurrent requests to avoid multiple refresh calls.
• For logout, call the backend logout API to invalidate/revoke the refresh token, then clear the refresh-token cookie on the frontend.

The key idea: the backend owns token rotation and revocation; Next.js mainly handles the cookie and request flow.

[Sarvagya-24-chaturvedi]

Hi @ahmedhammami-dev,

Handling rotating refresh tokens with HTTP-only cookies in Next.js 16 App Router has one major architectural constraint you must design around:

Crucial Next.js Constraint: Server Components (RSC) are read-only for cookies (cookies().set() throws an error in RSC because response headers have already streamed). Only Middleware, Server Actions, and Route Handlers can write cookies.

Because of this, the industry-standard production architecture is the Middleware Pre-emptive Refresh + Centralized Server Fetch Wrapper (BFF) pattern.

Here is the exact breakdown and recommended production architecture.

---

1. Responsibility Matrix: Who Does What?

Action	Recommended Layer	Why?
Pre-emptive Expiration Check	Middleware	Intercepts requests before RSC rendering. Checks JWT exp timestamp without calling the backend.
Token Rotation & Cookie Write	Middleware & Server Actions	Middleware rotates before page load and sets cookies on the response; Server Actions handle mutations.
Data Fetching & 401 Fallback	Custom fetchBackend Wrapper	Used inside Server Components and Server Actions to attach Bearer <access_token>.
Client-Side Requests	Route Handlers (BFF Proxy)	Browser calls /api/proxy/... with HTTP-only cookies; Route Handler forwards to backend.

---

2. How the Complete Request Lifecycle Works

A. Page Loads & Navigations (Server Components)

1. Middleware intercepts request: Checks the accessToken expiration (decode JWT payload locally, no backend roundtrip).
2. If token is expired (or < 60s remaining):
   • Middleware calls backend POST /auth/refresh using refreshToken (R1).
   • Backend returns new pair: A2 + R2.
   • Middleware sets new HTTP-only cookies on the outgoing response.
   • Crucial step for RSC: Middleware also updates the cookie header on the incoming request.headers so that downstream Server Components receive A2 on the very same render cycle.

B. Server Actions (Form submissions / Mutations)

• Server Actions can mutate cookies directly (cookies().set()).
• If a Server Action receives a 401 Unauthorized from your backend, your centralized fetch wrapper executes the refresh call, calls (await cookies()).set(), and retries the mutation once.

C. Client-Side Components

• The browser never handles the raw JWTs because they are HttpOnly.
• Client components make calls either via Server Actions or via Route Handlers (app/api/[...backend]/route.ts), which automatically forward the cookies.

---

3. How to Solve the Concurrent Request Race Condition (R1 Replay Attack)

When 3 Server Components or parallel fetches run simultaneously, they may all attempt to exchange R1 at the exact same millisecond. If the backend is strict, the 2nd and 3rd requests will be flagged as refresh token reuse / replay attacks and lock out the user.

In production, this is solved with a two-part strategy:

1. Backend Grace Period (Idempotency Window - Recommended):
   Configure your backend refresh token rotation to allow a brief grace period (e.g., 15–30 seconds) after rotation. If the backend receives R1 again during that window, it does not treat it as a breach; instead, it returns the already-generated A2 + R2.
2. In-Flight Promise De-duplication (BFF / Route Handler):
   If multiple requests arrive within the same Node/Edge runtime instance, store the active refresh promise in a variable so all concurrent requests await the single active rotation call:

   let activeRefreshPromise: Promise<TokenPair> | null = null;
   
   async function getFreshTokens(refreshToken: string) {
     if (!activeRefreshPromise) {
       activeRefreshPromise = callBackendRefresh(refreshToken).finally(() => {
         activeRefreshPromise = null;
       });
     }
     return activeRefreshPromise;
   }

---

4. Production Code Implementation

Step 1: Middleware (middleware.ts)

import { NextResponse, type NextRequest } from "next/server";

function isTokenExpired(token: string): boolean {
  try {
    const payload = JSON.parse(atob(token.split(".")[1]));
    // Buffer by 60 seconds to refresh before it dies in-flight
    return Date.now() >= (payload.exp * 1000) - 60000;
  } catch {
    return true;
  }
}

export async function middleware(request: NextRequest) {
  const accessToken = request.cookies.get("access_token")?.value;
  const refreshToken = request.cookies.get("refresh_token")?.value;

  // If no refresh token, let public routes pass or redirect to login
  if (!refreshToken) {
    return NextResponse.next();
  }

  // If accessToken is still valid, continue normally
  if (accessToken && !isTokenExpired(accessToken)) {
    return NextResponse.next();
  }

  // Token is expired -> Rotate tokens
  try {
    const res = await fetch(`${process.env.BACKEND_API_URL}/auth/refresh`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ refreshToken }),
    });

    if (!res.ok) throw new Error("Refresh failed");

    const { accessToken: newAccess, refreshToken: newRefresh } = await res.json();

    // 1. Prepare response to update client cookies
    const response = NextResponse.next({
      request: {
        headers: new Headers(request.headers),
      },
    });

    // 2. Set new cookies for browser
    response.cookies.set("access_token", newAccess, { httpOnly: true, secure: true, sameSite: "lax" });
    response.cookies.set("refresh_token", newRefresh, { httpOnly: true, secure: true, sameSite: "lax" });

    // 3. Forward new access token to Server Components in current request
    response.headers.set("x-access-token", newAccess);

    return response;
  } catch {
    // Refresh failed or revoked -> Clear cookies and redirect to login
    const response = NextResponse.redirect(new URL("/login", request.url));
    response.cookies.delete("access_token");
    response.cookies.delete("refresh_token");
    return response;
  }
}

export const config = {
  matcher: ["/((?!_next/static|_next/image|favicon.ico).*)"],
};

Step 2: Centralized Fetch Wrapper for Server Components (lib/api.ts)

import { headers, cookies } from "next/headers";

export async function fetchBackend(endpoint: string, options: RequestInit = {}) {
  const headerList = await headers();
  const cookieStore = await cookies();

  // Pick token forwarded by middleware or existing cookie
  const token = headerList.get("x-access-token") || cookieStore.get("access_token")?.value;

  const res = await fetch(`${process.env.BACKEND_API_URL}${endpoint}`, {
    ...options,
    headers: {
      ...options.headers,
      Authorization: `Bearer ${token}`,
      "Content-Type": "application/json",
    },
  });

  return res;
}

---

Summary Checklist for Production

1. Pre-check in Middleware: Keep your pages fast by checking the JWT exp locally. Only call /refresh when the token is near expiration.
2. Forward with headers: Pass the fresh access token via request headers (x-access-token) in Middleware so downstream Server Components don't see an outdated token.
3. Backend Grace Window: Ensure your backend rotation logic has a 10–30s grace window for the previous refresh token to prevent concurrency lockouts.

[Michealshodipo56]

For production, I would avoid making every matched proxy.ts request independently responsible for refresh-token rotation. Proxy also runs for prefetched routes, so parallel navigations can easily race.

The most robust design is:

1. Store a stable, opaque session ID in the browser's HttpOnly, Secure, SameSite cookie.
2. Store the access and refresh tokens server-side, indexed by that session ID.
3. Put token validation and refresh in one server-only service used by Server Components, Server Actions, and Route Handlers.
4. Let the external backend remain responsible for token validation, rotation, revocation, and replay detection.

This avoids the Server Component cookie-write problem entirely. Server Components can read the stable session cookie, while refreshed token pairs are updated in the server-side store rather than requiring a new browser cookie after every rotation.

For concurrent requests, use distributed coordination keyed by session ID:

• Read the session and check whether refresh is needed.
• Acquire a short-lived distributed lock.
• Re-read the session after acquiring the lock.
• Refresh only if another request has not already done so.
• Atomically replace the stored token pair/version.
• Release the lock and allow waiting requests to use the new pair.

A process-local promise map helps on one instance but is insufficient when requests reach different instances. The authentication backend should also support a bounded idempotency or grace window for concurrent uses of the previous refresh token.

If tokens must remain in browser cookies, refresh through a Route Handler or Server Action that returns directly to the browser and can emit Set-Cookie. An internal fetch performed during Server Component rendering cannot forward its response cookies to the browser. Proxy can perform a proactive refresh, but it needs the same distributed coordination and should be carefully scoped.

Additional safeguards:

• Retry only once after a confirmed token-expiry response.
• Do not automatically replay non-idempotent mutations unless they use an idempotency key.
• Do not clear the session for timeouts, 429, or 5xx responses; distinguish outages from invalid or revoked refresh tokens.
• Never place access tokens in client-visible response headers or JSON.
• Treat decoding exp as a refresh optimization, not authorization; the backend must still validate the token.
• Protect cookie-authenticated mutations against CSRF.

This follows Next.js's documented model: Server Components can read cookies but cannot set them, while Server Functions and Route Handlers can write cookies. Proxy is best suited to optimistic checks rather than being the only security boundary.

References: Authentication guide, cookies(), and Backend-for-Frontend guide.

[halilertekin]

One concrete concurrency issue in the examples above is worth fixing before choosing the refresh layer: a single module-level activeRefreshPromise is shared by all sessions handled by that process.

If Alice starts a refresh and Bob arrives while it is pending, Bob awaits Alice's promise. If the caller then writes that returned token pair to Bob's response cookies, it crosses the session boundary. This is different from two requests by the same user racing over R1.

I checked that behavior with a small Node.js test using synthetic tokens: the global-promise version returned Alice's result to both callers. A coordinator keyed by session kept Alice/Bob separate, deduplicated two calls for the same session, and allowed a retry after rejection.

For illustration, this is process-local deduplication only, not a complete rotation protocol:

function singleFlight(refresh) {
  const inFlight = new Map();
  return (sessionId, refreshToken) => {
    const existing = inFlight.get(sessionId);
    if (existing) return existing;
    const pending = Promise.resolve()
      .then(() => refresh(refreshToken))
      .finally(() => {
        if (inFlight.get(sessionId) === pending) inFlight.delete(sessionId);
      });
    inFlight.set(sessionId, pending);
    return pending;
  };
}

Derive the session key from authenticated server-side state. Across instances, coordination must live in the auth backend/shared session service; after acquiring it, re-read the current token version before rotating. This helper does not resolve stale R1 requests arriving after the promise is removed, worker crashes, or out-of-order browser cookie writes. Those need an explicit backend rotation/retry contract.

For the Next.js split, the server-side session/BFF approach already described above fits this well: one stable browser session ID, with token pairs updated server-side. If keeping tokens in browser cookies, refresh through a browser-visible Route Handler/Server Action (or carefully scoped Proxy); an internal RSC fetch does not deliver its Set-Cookie to the browser.

Next.js documents both the cookie-write restriction during Server Component rendering and that Proxy should not rely on shared globals. I would test two different users concurrently as well as two requests for one user before deploying either design.

[elladeniya-dev]

When using a separate backend API with rotating refresh tokens and HttpOnly cookies in Next.js 16, the main issue is that Server Components (RSC) cannot set cookies during rendering, and parallel RSC requests can cause race conditions if two requests try to rotate the same refresh token at the same time.

Here is the cleanest pattern to handle this in Next.js 16:

1. Centralize Token Refresh in proxy.ts (or middleware.ts)

Because proxy.ts / middleware.ts runs before Server Components render and can modify both request and response headers, it is the best place during navigation to rotate the token and forward the Set-Cookie header back to the browser:

import { NextResponse, type NextRequest } from 'next/server';

export async function middleware(request: NextRequest) {
  const accessToken = request.cookies.get('access_token')?.value;
  const refreshToken = request.cookies.get('refresh_token')?.value;

  if (!accessToken && refreshToken) {
    const refreshRes = await fetch('[https://api.example.com/auth/refresh](https://api.example.com/auth/refresh)', {
      method: 'POST',
      headers: { Cookie: `refresh_token=${refreshToken}` },
    });

    if (refreshRes.ok) {
      const response = NextResponse.next();
      const setCookieHeaders = refreshRes.headers.getSetCookie();
      setCookieHeaders.forEach((cookie) => {
        response.headers.append('Set-Cookie', cookie);
      });
      return response;
    } else {
      const loginUrl = new URL('/login', request.url);
      const response = NextResponse.redirect(loginUrl);
      response.cookies.delete('access_token');
      response.cookies.delete('refresh_token');
      return response;
    }
  }

  return NextResponse.next();
}

2. Add a Short Reuse Grace Window on the Backend

Because App Router prefetches routes in parallel, two requests might send the same refresh token within milliseconds. Configure your backend to allow a 5–10 second grace window on a just-rotated refresh token so parallel requests don't trigger false token-reuse revocation.

3. Use a BFF Route Handler (/api/auth/refresh) for Client Components

For client-side fetches, use an Axios/fetch interceptor with a shared Promise lock that calls /api/auth/refresh so multiple 401s on the client wait on a single refresh request.

Hope this helps! If this answers your question, feel free to mark it as the answer.