3.x to 4.x of the Auth0 Next.js SDK.
Environment Variables
The following environment variables are required in v4:Auth0Client constructor.
In v3 the
audience parameter could be specified via the AUTH0_AUDIENCE environment variable. In v4, the audience parameter must be specified as a query parameter or via the authorizationParameters configuration option. For more information on how to pass custom parameters in v4, please see Passing custom authorization parameters.Routes
Previously, it was required to set up a dynamic Route Handler to mount the authentication endpoints to handle requests. For example, in v3 when using the App Router, you were required to create a Route Handler, under/app/api/auth/[auth0]/route.ts, with the following contents:
The Auth0 Middleware
In v4, the Auth0 middleware is a central component of the SDK. It serves a number of core functions such as registering the required authentication endpoints, providing rolling sessions functionality, keeping access tokens fresh, etc. When configuring your application to use v4 of the SDK, it is now required to mount the middleware:The above middleware is a basic setup. It passes incoming requests to the Auth0 SDK’s request handler, which in turn manages the default auto-mounted authentication routes, user sessions, and the overall authentication flow. It does not protect any routes by default. To protect routes from unauthenticated users, read the section below on protecting routes.
Protecting Routes
By default, the middleware does not protect any routes. To protect a page, you can use thegetSession() handler in the middleware, like so:
We recommend keeping the security checks as close as possible to the data source you’re accessing. This is also in-line with the recommendations from the Next.js team.
Combining with Other Middleware
For scenarios where you need to combine the Auth0 middleware with other Next.js middleware, please refer to the Combining Middleware guide for examples and best practices.Migrating <UserProvider /> to <Auth0Provider />
Previously, when setting up your application to use v3 of the SDK, it was required to wrap your layout in the <UserProvider />. This is no longer required by default.
If you would like to pass an initial user during server rendering to be available to the useUser() hook, you can wrap your components with the new <Auth0Provider />.
Rolling Sessions
In v4, rolling sessions are enabled by default and are handled automatically by the middleware with no additional configuration required. See the session configuration section for additional details on how to configure it.Migrating from withPageAuthRequired and withApiAuthRequired
Instead, we recommend adding a getSession() check or relying on useUser() hook where you would have previously used the helpers.
Server-Side Authentication Check
On the server-side, thegetSession() method can be used to check if the user is authenticated:
- App Router
- Pages Router
getSession() method can be used in the App Router in Server Components, Server Routes (APIs), Server Actions, and middleware.
In the Pages Router, the getSession(req) method takes a request object and can be used in getServerSideProps, API routes, and middleware.
Client-Side Authentication Check
In the browser, you can rely on theuseUser() hook to check if the user is authenticated:
Passing Custom Authorization Parameters
- v4 (Query Parameters)
- v4 (Static Configuration)
- v3 (Old Approach)
In v4, you can simply append the authorization parameters to the query parameter of the login endpoint and they will be automatically forwarded to the
/authorize endpoint:In previous versions,
authParams was used. In v4, use authorizationParameters. For example, for silent authentication: authorizationParameters: { prompt: 'none' }.ID Token Claims
In v3, any claims added to the ID token were automatically propagated to theuser object in the session. This resulted in large cookies that exceeded browser limits.
If you’d like to customize the user object to include additional custom claims from the ID token, you can use the beforeSessionSaved hook. For a list of default claims included in the user object, refer to the ID Token claims and the user object section in the Examples guide.
Handling Dynamic Base URLs
When deploying to platforms like Vercel with dynamic preview URLs, it’s important to set the correctappBaseUrl and redirect_uri at runtime — especially in preview environments where URLs change per deployment.
Additional Changes
Edge Compatibility
By default, v4 is edge-compatible and as such there is no longer a@auth0/nextjs-auth0/edge export.
Cookie Configuration
All cookies set by the SDK default toSameSite=Lax. For details on how to customize cookie attributes, see the Cookie Configuration section in the Examples guide.
Touch Session Removed
touchSession method was removed. The middleware enables rolling sessions by default and can be configured via the Session configuration section in the Examples guide.
Access Token in React Server Components
getAccessToken can now be called in React Server Components. For examples on how to use getAccessToken in various environments (browser, App Router, Pages Router, Middleware), refer to the Getting an access token section in the Examples guide.
Logout Behavior
By default, v4 will use OpenID Connect’s RP-Initiated Logout if it’s enabled on the tenant. Otherwise, it will fallback to the/v2/logout endpoint.
Profile Route 401 Response
The v4/auth/profile profile route returns a 401 Unauthorized error when unauthenticated. If you would like to replicate the v3 behaviour where the profile route returns a 204 response, enable noContentProfileResponseWhenUnauthenticated in Auth0ClientOptions. This prevents the SDK from automatically retrying the error when the user is logged out.
Customizing Auth Handlers
In v3, you could customize individual auth handlers by providing custom implementations to thehandleAuth function:
Run Custom Code Before Auth Handlers (Middleware Interception)
You can intercept auth routes in your middleware to run custom logic before the auth handlers execute:Run Code After Authentication (Callback Hook)
Use theonCallback hook to add custom logic after authentication completes:
Additional Customization Options
- Login parameters: Use query parameters (
/auth/login?audience=...) or static configuration - Session data: Use the
beforeSessionSavedhook to modify session data - Logout redirects: Use query parameters (
/auth/logout?returnTo=...) - Transaction cookies: Configure transaction cookie behavior with
TransactionStoreoptions. See Transaction Cookie Configuration for details.
Transaction Cookie Management
V4 introduces improved transaction cookie management to prevent cookie accumulation issues that could cause HTTP 413 errors. TheTransactionStore now supports configurable parallel transactions to control whether multiple login flows can run simultaneously.
- Default Behavior
- Custom Configuration
In contrast, V3 did not support parallel transactions.