v4: Advanced auth scenarios (token renewal, session management, parallel requests)

[atomicbrainman]

Checklist

• The issue can be reproduced in the nextjs-auth0 sample app (or N/A).
• I have looked into the Readme, Examples, and FAQ and have not found a suitable solution or answer.
• I have looked into the API documentation and have not found a suitable solution or answer.
• I have searched the issues and have not found a suitable solution or answer.
• I have searched the Auth0 Community forums and have not found a suitable solution or answer.
• I agree to the terms within the Auth0 Code of Conduct.

Description

The current documentation and examples don't seem to contain complete solutions for more complex auth flows.

Reproduction

Context

• Next.js app uses App Router only
• Refresh tokens are rotated on each use
• Auth is checked in the Middleware according to the Examples doc:

const authRes = await auth0.middleware(request)

if (isPublicRoute() || isAuthRoute()) {
  return authRes
}

const session = await auth0.getSession(request)

if (!session) {
  return redirectToLogin() // Default "/auth/login"
}

Flow 1: Access token expiration when there is no Refresh token and Auth0 doesn't have a custom domain set

Having the app on app.com and auth on something.auth0.com means that Route Handler redirects will be blocked due to CORS issues.
This also applies to local development, even if Auth0 has a custom domain set.

The Examples doc states:
Getting an access token > On the server (App Router) > Important

It is recommended to call getAccessToken(req, res) in the middleware if you need to use the refresh token in a Server Component as this will ensure the token is refreshed and correctly persisted.

Which is discouraged by Next.js Middleware docs:

Middleware is not a good fit for:

• Session management

But assuming the Access token is handled in the Middleware with this check:

const accessToken = await auth0.getAccessToken(request, authRes)

The user will receive this message:

"The access token has expired and a refresh token was not provided. The user needs to re-authenticate."

We can wrap the getAccessToken() in try / catch and redirect the user to the login page:

try {
  const accessToken = await auth0.getAccessToken(request, authRes)
} catch (error) {
  if (error instanceof AccessTokenError) {
    return redirectToLogin()
  }

  ...
}

Is this the correct way to handle such cases?
This will work for browser routing requests, but not for Route Handler API requests, which will appear as:
app.com/api/test > (Redirect to) app.com/auth/login > (Redirect to) something.auth0.com/authorize
And this will be blocked by CORS.
It looks like the only solution to this is for the request to return 401 in such cases, so that the client could trigger a proper redirect.

Executing getAccessToken() in the Middleware introduces other issues as well:

• If the request was initiated by a Client component and was going through a Route Handler and the session is updated in the Middleware, the Route Handler gets the old session with await auth0.getSession(request) and is unable to do anything, because the old Refresh token was rotated and is no longer valid.

Instead of adding getAccessToken() in the Middleware, server components could fetch the data using existing Route Handlers, which allow setting cookies.
But this requires cookie forwarding:

export default async function ServerComponent() {
  const cookieStore = await cookies()
  const response = fetch('app.com/api/test', {
    headers: {
      Cookies: cookieStore.toString(),
    },
  })
}

The downsides I see here:

• The need to ensure these cookies are not sent to a third party
• Two requests instead of one, increasing the response time and server load
• Are there other potential issues?

An even better approach is to use Server Actions from Server components and use the redirect() helper.

Flow 2: Token renewal during parallel requests

Let's say we have multiple parallel requests from Client components going through Route Handlers when the Access token is expired.
I assumed there should be an Internal Locking / Request Coalescing mechanism that would enforce a maximum of one simultaneous token renewal request per user. So that parallel requests would all wait until the tokens are renewed.
However, such a mechanism doesn't seem to be present. Instead, each parallel request tries renewing the tokens, but only the first one succeeds, while others result in an error, because the Refresh token was rotated and is no longer valid.

What is the suggested approach here?

Flow 3: Setting Access token expiration buffer

The current implementation of getAccessToken() refreshes the tokens only after they have already expired:

nextjs-auth0/src/server/auth-client.ts

Line 706 in 0ed21d1

if (forceRefresh || tokenSet.expiresAt <= Date.now() / 1000) {

But this may lead to an issue where the token expires after the frontend check, but before it's actually checked by the backend. Or if there's a slight time mismatch between the frontend and backend.
It seems reasonable to add a small default buffer (e.g. 15 seconds) and refresh the tokens shortly before they have actually expired.

This could likely be achieved by manually passing the refresh param, though a global setting seems preferable:

const accessToken = await auth0.getAccessToken(request, authRes, {
  refresh: session.tokenSet.expiresAt - 15 <= Date.now() / 1000,
})

Flow 4: Session / Id token expiration when Access token is not used

If the audience param is empty or if await getAccessToken() is not used, the user might have an expired session / Id token.
What is the correct way to handle this?

nextjs-auth0/src/types/index.ts

Lines 17 to 28 in 0ed21d1

	export interface SessionData {
	user: User;
	tokenSet: TokenSet;
	internal: {
	// the session ID from the authorization server
	sid: string;
	// the time at which the session was created in seconds since epoch
	createdAt: number;
	};
	connectionTokenSets?: ConnectionTokenSet[];
	[key: string]: unknown;
	}

The session object has:

• An untyped session.exp - this one looks like it's driven by the Auth0Client inactivityDuration / absoluteDuration params
• session.tokenSet.expiresAt - is this the same as Id token's expiration time?

Flow 5: Immediate re-authentication after the user returns to an inactive page with an expired session

What is the suggested approach to check and handle this case?

Flow 6: Silent authentication

Asked here:
#2128

Additional

It would be great to have examples that show how to handle token renewal, session management and both server-side and client-side requests in a single integrated solution.

Additional context

• Next.js app uses App Router only
• Refresh tokens are rotated on each use

nextjs-auth0 version

4.6.0

Next.js version

15.3

Node.js version

22

[thomashzhang]

Flow 3 is very important to us as well

[tusharpandey13]

Hi @atomicbrainman 👋, apologies for the delayed response on this.
Thanks for the detailed description, we are actively looking into all these and will get back to you soon on this, with sppropriate changes to documentation / PRs if needed.

[atomicbrainman]

Hi @tusharpandey13,

Thanks for the response. Following up on this after some deeper investigation into the architectural patterns required by modern React and Next.js. I'm still seeing some CORS issues even with a custom domain set, but I suspect that's an issue within the Auth0 dashboard and likely unrelated to the library itself.

The core of the problem seems to be a set of fundamental constraints that make robust session management, especially with token rotation, very challenging.

Core Next.js & React Constraints

• Server Components have read-only cookie access. This prevents them from persisting a renewed session.
• Server Actions are client-invoked only. As noted in Error: Cookies can only be modified in a Server Action or Route Handler. vercel/next.js#51875, calling them from a Server Component executes them as a simple function, so they can't be used for a server-initiated session update.
• Internal fetch from Server Components to Route Handlers is a dead end for setting cookies. Calling a Route Handler from a Server Component to refresh a token creates a new, self-contained request. Any Set-Cookie headers on the Route Handler's response are dropped and do not reach the browser. This makes the BFF proxy pattern non-viable for Server Components.

The Problem with Middleware for Server Components

These constraints seem to push all responsibility for Server Component session renewal onto Middleware. However, this approach has significant drawbacks:

• Performance: A wide matcher slows down the entire user experience. Even on the "happy path", decrypting encrypted session cookies (which may be split into multiple chunks) on every request, including prefetches, adds unavoidable overhead.
• Impact on Next.js Features: Redirecting on an expired session from middleware breaks key features:
  • Link Prefetching: The prefetch is redirected to the login page, wasting resources and slowing down the eventual navigation.
  • Server Action Invocations: The client expects a JSON response from the action but receives HTML from the redirect, breaking the form's state and UI.
• Failed Token Persistence: When the middleware successfully renews an access token during a prefetch or Server Action without a redirect, it cannot reliably persist the new session to the browser. This creates a "one-time-use" token, where the renewal is valid for the immediate operation but is not saved for subsequent requests, forcing the next user navigation to trigger the same expensive renewal process again.

Challenges with Parallel Requests and Refresh Token Rotation

Parallel requests create critical race conditions that make session management unreliable.

Server-Side "Stale Token" Problem (Auth management done in Middleware)

When authentication management, including token renewal, is handled in middleware, a successful renewal results in a Set-Cookie header being added to the outgoing response destined for the browser. However, Server Components rendering within the same request-response cycle can only access the original cookies from the incoming request. Middleware can modify request headers, but it cannot modify the cookie collection that Server Components read via cookies(). This creates a "stale token" problem where the components proceed to use the old, expired access token for their data-fetching API calls, causing those fetches to fail at the backend.

Client-Side Race Condition (Auth management done in BFF Route Handler)

Parallel useSWR fetches from client components hit the BFF proxy simultaneously. With Refresh Token Rotation enabled, the first renewal request invalidates the refresh token. All other concurrent requests then fail because they hold a now-stale token, leading to an inconsistent and broken UI. If Refresh Token Rotation is disabled, the parallel requests won't fail, but will still cause a "Thundering Herd" of unnecessary renewal calls to the auth provider.

Given these points, supporting Refresh Token Rotation appears impossible to do reliably without a robust, server-side request coalescing mechanism to handle these race conditions.