@auth0/nextjs-auth0 - v4.18.0
@auth0/nextjs-auth0 - v4.19.0
The Auth0 Next.js SDK is a library for implementing user authentication in Next.js applications.
📚 Documentation - 🚀 Getting Started - 💻 API Reference - 💬 Feedback
-Documentation
--
+
- QuickStart - our guide for adding Auth0 to your Next.js app.
- Examples - lots of examples for your different use cases.
- Security - Some important security notices that you should check.
- Docs Site - explore our docs site and learn more about Auth0.
Documentation
Getting Started
-1. Install the SDK
-npm i @auth0/nextjs-auth0
+Getting Started
1. Install the SDK
npm i @auth0/nextjs-auth0
This library requires Node.js 20 LTS and newer LTS versions.
-2. Add the environment variables
-Add the following environment variables to your .env.local file:
+2. Add the environment variables
Add the following environment variables to your .env.local file:
AUTH0_DOMAIN=
AUTH0_CLIENT_ID=
AUTH0_CLIENT_SECRET=
@@ -42,8 +38,7 @@ 2. Add the envi
When using dynamic hosts (preview environments), ensure the resulting callback and logout URLs are registered in your Auth0 application.
Dynamic base URLs (Preview deployments)
-For preview environments (Vercel, Netlify), you can omit APP_BASE_URL and let the SDK infer the base URL from the incoming request host at runtime. This keeps dynamic preview URLs working without extra configuration.
Dynamic base URLs (Preview deployments)
For preview environments (Vercel, Netlify), you can omit APP_BASE_URL and let the SDK infer the base URL from the incoming request host at runtime. This keeps dynamic preview URLs working without extra configuration.
If you know the base URL at startup (for example, a stable production domain), set appBaseUrl or APP_BASE_URL to a single absolute URL. Comma-separated values are not supported.
Because the Host header is untrusted input, Auth0's Allowed Callback URLs are the safety net in this mode: if the inferred host is not registered, Auth0 rejects the authorize request.
Example (dynamic):
@@ -57,8 +52,7 @@Dynamic b
Note
When relying on dynamic base URLs in production, the SDK enforces secure cookies. If you explicitly set AUTH0_COOKIE_SECURE=false, session.cookie.secure=false, or transactionCookie.secure=false, the SDK throws InvalidConfigurationError.
-3. Create the Auth0 SDK client
-
When relying on dynamic base URLs in production, the SDK enforces secure cookies. If you explicitly set AUTH0_COOKIE_SECURE=false, session.cookie.secure=false, or transactionCookie.secure=false, the SDK throws InvalidConfigurationError.
Create an instance of the Auth0 client. This instance will be imported and used in anywhere you need access to the authentication methods on the server.
+3. Create the Auth0 SDK client
Create an instance of the Auth0 client. This instance will be imported and used in anywhere you need access to the authentication methods on the server.
Add the following contents to a file named lib/auth0.ts:
import { Auth0Client } from "@auth0/nextjs-auth0/server";
export const auth0 = new Auth0Client();
3. Create the Aut
Note
The Auth0Client automatically uses safe defaults to manage authentication cookies. For advanced use cases, you can customize transaction cookie behavior by providing your own configuration. See Transaction Cookie Configuration for details.
-4. Add the authentication middleware
-
The Auth0Client automatically uses safe defaults to manage authentication cookies. For advanced use cases, you can customize transaction cookie behavior by providing your own configuration. See Transaction Cookie Configuration for details.
Authentication requests in Next.js are intercepted at the network boundary using a middleware or proxy file.
+
4. Add the authentication middleware
Authentication requests in Next.js are intercepted at the network boundary using a middleware or proxy file.
Follow the setup below depending on your Next.js version.
🟦 On Next.js 15
-Create a middleware.ts file in the root of your project:
🟦 On Next.js 15
Create a middleware.ts file in the root of your project:
import type { NextRequest } from "next/server";
import { auth0 } from "./lib/auth0"; // Adjust path if your auth0 client is elsewhere
export async function middleware(request: NextRequest) {
return await auth0.middleware(request);
}
export const config = {
matcher: [
/*
* Match all request paths except for:
* - _next/static (static files)
* - _next/image (image optimization files)
* - favicon.ico, sitemap.xml, robots.txt (metadata files)
*/
"/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)"
]
};
If you're using a src/ directory, the middleware.ts file must be created inside the src/ directory.
🟨 On Next.js 16
-Next.js 16 introduces a new convention called proxy.ts, replacing middleware.ts. +
🟨 On Next.js 16
Next.js 16 introduces a new convention called proxy.ts, replacing middleware.ts. This change better represents the network interception boundary and unifies request handling for both the Edge and Node runtimes.
Create a proxy.ts file in the root of your project (Or rename your existing middleware.ts to proxy.ts):
@@ -101,8 +92,7 @@🟨 On Next.js 16Important
You must use <a> tags instead of the <Link> component to ensure that the routing is not done client-side as that may result in some unexpected behavior.
You must use
<a> tags instead of the <Link> component to ensure that the routing is not done client-side as that may result in some unexpected behavior.Customizing the client
-You can customize the client by using the options below:
+Customizing the client
You can customize the client by using the options below:
| cspNonce | +string |
+CSP nonce for inline scripts in popup callback HTML responses. When provided, <script> tags in the MFA popup callback include a nonce="..." attribute for strict Content Security Policy compliance. Only required when using mfa.challengeWithPopup() with a CSP that blocks inline scripts. |
+
| discoveryCache | DiscoveryCacheOptions |
Configure the OIDC discovery metadata cache for Multiple Custom Domains. Controls TTL and maximum cached issuers. |
Customizing Auth Handlers
-While the authentication routes are handled automatically by the middleware, you can still customize the authentication flow through two main approaches:
+Customizing Auth Handlers
While the authentication routes are handled automatically by the middleware, you can still customize the authentication flow through two main approaches:
- Run custom code before auth handlers: Intercept auth routes in your middleware to add custom logic before authentication actions
- Run code after authentication: Use the
onCallbackhook to add custom logic after authentication completes
@@ -260,8 +254,7 @@
Customizing Auth Hand When customizing auth handlers, always validate user inputs (especially redirect URLs) to prevent security vulnerabilities like open redirects. Use relative URLs when possible and implement proper input sanitization.
Quick Start: For detailed examples and step-by-step migration patterns from v3, see Customizing Auth Handlers.
-Session Cookie Configuration
-You can specify the following environment variables to configure the session cookie:
+Session Cookie Configuration
You can specify the following environment variables to configure the session cookie:
AUTH0_COOKIE_DOMAIN=
AUTH0_COOKIE_PATH=
AUTH0_COOKIE_TRANSIENT=
@@ -273,10 +266,8 @@ Session Cookie Con
AUTH0_DPOP_CLOCK_TOLERANCE=
DPoP Configuration
-The Auth0 Next.js SDK supports DPoP (Demonstrating Proof-of-Possession) for enhanced OAuth 2.0 security. DPoP binds access tokens to cryptographic key pairs, preventing token theft and replay attacks.
-Quick Start
-Option 1: Environment Variables
+DPoP Configuration
The Auth0 Next.js SDK supports DPoP (Demonstrating Proof-of-Possession) for enhanced OAuth 2.0 security. DPoP binds access tokens to cryptographic key pairs, preventing token theft and replay attacks.
+Quick Start
Option 1: Environment Variables
# Enable DPoP and provide ES256 key pair
AUTH0_DPOP_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----
MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE...
@@ -293,16 +284,14 @@ Quick Startimport { Auth0Client } from "@auth0/nextjs-auth0/server";
import { generateKeyPair } from "oauth4webapi";
const dpopKeyPair = await generateKeyPair("ES256");
export const auth0 = new Auth0Client({
useDPoP: true,
dpopKeyPair,
dpopOptions: {
clockTolerance: 30, // Allow 30s clock difference
retry: {
delay: 100, // 100ms retry delay
jitter: true // Add randomness
}
}
});
Making DPoP-Protected Requests
-// Create a fetcher - DPoP inherited from global configuration
const fetcher = await auth0.createFetcher(req, {
baseUrl: "https://api.example.com"
// useDPoP is inherited from Auth0Client config
});
// Make authenticated requests with automatic DPoP proof generation
const response = await fetcher.fetchWithAuth("/protected-resource", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ data: "example" })
});
+Making DPoP-Protected Requests
// Create a fetcher - DPoP inherited from global configuration
const fetcher = await auth0.createFetcher(req, {
baseUrl: "https://api.example.com"
// useDPoP is inherited from Auth0Client config
});
// Make authenticated requests with automatic DPoP proof generation
const response = await fetcher.fetchWithAuth("/protected-resource", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ data: "example" })
});
DPoP Inheritance Behavior
Fetchers created with createFetcher automatically inherit the global DPoP configuration from your Auth0Client instance.
This inheritance pattern follows the same behavior as auth0-spa-js, providing consistent developer experience across Auth0 SDKs.
For complete DPoP documentation, examples, and best practices, see DPoP Examples.
-Advanced: Clock Validation Configuration
-Configure timing validation for DPoP proofs to handle clock differences between client and server:
+Advanced: Clock Validation Configuration
Configure timing validation for DPoP proofs to handle clock differences between client and server:
export const auth0 = new Auth0Client({
useDPoP: true,
dpopKeyPair: await generateKeyPair("ES256"),
dpopOptions: {
clockSkew: 120, // Adjust for local clock being 2 minutes behind
clockTolerance: 45 // Allow 45 seconds tolerance for validation
}
});
@@ -312,36 +301,30 @@ Advance
Respective counterparts are also available in the client configuration. See Cookie Configuration for more details.
-Proxy Handler for My Account and My Organization APIs
-The SDK provides built-in proxy support for Auth0's My Account and My Organization Management APIs, enabling secure browser-initiated requests while maintaining server-side DPoP authentication and token management.
-How It Works
-The proxy handler automatically intercepts requests to /me/* and /my-org/* paths in your Next.js application and forwards them to the respective Auth0 APIs with proper authentication headers. This implements a Backend-for-Frontend (BFF) pattern where:
Proxy Handler for My Account and My Organization APIs
The SDK provides built-in proxy support for Auth0's My Account and My Organization Management APIs, enabling secure browser-initiated requests while maintaining server-side DPoP authentication and token management.
+How It Works
The proxy handler automatically intercepts requests to /me/* and /my-org/* paths in your Next.js application and forwards them to the respective Auth0 APIs with proper authentication headers. This implements a Backend-for-Frontend (BFF) pattern where:
- Tokens and DPoP keys remain on the server
- Access tokens are automatically retrieved or refreshed
- DPoP proofs are generated for each request
- Session updates occur transparently
Configuration
-Configure audience and scopes for the APIs:
+Configuration
Configure audience and scopes for the APIs:
import { Auth0Client } from "@auth0/nextjs-auth0/server";
export const auth0 = new Auth0Client({
useDPoP: true,
authorizationParameters: {
audience: "urn:your-api-identifier",
scope: {
[`https://${process.env.AUTH0_DOMAIN}/me/`]: "profile:read profile:write",
[`https://${process.env.AUTH0_DOMAIN}/my-org/`]: "org:read org:write"
}
}
});
Client-Side Usage
-Make requests through the proxy paths:
+Client-Side Usage
Make requests through the proxy paths:
// My Account API
const response = await fetch("/me/v1/profile", {
headers: { "scope": "profile:read" }
});
// My Organization API
const response = await fetch("/my-org/organizations", {
headers: { "scope": "org:read" }
});
The scope header specifies the required scope. The SDK retrieves an access token with the appropriate audience and scope, then forwards the request with authentication headers.
For complete documentation, examples, and integration patterns with UI Components, see Proxy Handler for My Account and My Organization APIs.
-Base Path
-Your Next.js application may be configured to use a base path (e.g.: /dashboard) — this is usually done by setting the basePath option in the next.config.js file. To configure the SDK to use the base path, you will also need to set the NEXT_PUBLIC_BASE_PATH environment variable which will be used when mounting the authentication routes.
Base Path
Your Next.js application may be configured to use a base path (e.g.: /dashboard) — this is usually done by setting the basePath option in the next.config.js file. To configure the SDK to use the base path, you will also need to set the NEXT_PUBLIC_BASE_PATH environment variable which will be used when mounting the authentication routes.
For example, if the NEXT_PUBLIC_BASE_PATH environment variable is set to /dashboard, the SDK will mount the authentication routes on /dashboard/auth/login, /dashboard/auth/callback, /dashboard/auth/profile, etc.
We do not recommend using the NEXT_PUBLIC_BASE_PATH environment variable in conjunction with a APP_BASE_URL that contains a path component. If your application is configured to use a base path, you should set the APP_BASE_URL to the root URL of your application (e.g.: https://example.com) and use the NEXT_PUBLIC_BASE_PATH environment variable to specify the base path (e.g.: /dashboard).
Configuration Validation
-The SDK performs validation of required configuration options when initializing the Auth0Client. The following options are mandatory and must be provided either through constructor options or environment variables:
Configuration Validation
The SDK performs validation of required configuration options when initializing the Auth0Client. The following options are mandatory and must be provided either through constructor options or environment variables:
domain(orAUTH0_DOMAINenvironment variable)clientId(orAUTH0_CLIENT_IDenvironment variable)
@@ -355,14 +338,12 @@
Configuration Validati
If any of these required options are missing, the SDK will issue a warning with a detailed message explaining which options are missing and how to provide them.
appBaseUrl is optional; if omitted, the SDK will infer it from the request host at runtime.
Multiple Custom Domains (MCD)
-The SDK supports authenticating users against multiple Auth0 custom domains on the same tenant. Pass a DomainResolver function as the domain option to enable per-request domain resolution:
Multiple Custom Domains (MCD)
The SDK supports authenticating users against multiple Auth0 custom domains on the same tenant. Pass a DomainResolver function as the domain option to enable per-request domain resolution:
import { Auth0Client } from "@auth0/nextjs-auth0/server";
export const auth0 = new Auth0Client({
domain: ({ headers }) => {
const host = headers.get("host") ?? "";
if (host.startsWith("brand1.")) return "auth.brand1.com";
return "auth.default.com";
}
});
For complete documentation, configuration options, and examples, see Multiple Custom Domains in EXAMPLES.md.
-Routes
-The SDK mounts 6 routes:
+Routes
The SDK mounts 6 routes:
/auth/login: the login route that the user will be redirected to to initiate an authentication transaction/auth/logout: the logout route that must be added to your Auth0 application's Allowed Logout URLs
@@ -380,20 +361,15 @@
RoutesImportant
The /auth/access-token route is enabled by default, but is only necessary when the access token is needed on the client-side. If this isn't something you need, you can disable this endpoint by setting enableAccessTokenEndpoint to false.
The
/auth/access-token route is enabled by default, but is only necessary when the access token is needed on the client-side. If this isn't something you need, you can disable this endpoint by setting enableAccessTokenEndpoint to false.Feedback
-Contributing
-We appreciate feedback and contribution to this repo! Before you get started, please read the following:
+Feedback
Contributing
We appreciate feedback and contribution to this repo! Before you get started, please read the following:
- Auth0's general contribution guidelines
- Auth0's code of conduct guidelines
- This repo's contribution guide
Raise an issue
-To provide feedback or report a bug, please raise an issue on our issue tracker.
-Vulnerability Reporting
-Please do not report security vulnerabilities on the public GitHub issue tracker. The Responsible Disclosure Program details the procedure for disclosing security issues.
-What is Auth0?
-+
Raise an issue
To provide feedback or report a bug, please raise an issue on our issue tracker.
+Vulnerability Reporting
Please do not report security vulnerabilities on the public GitHub issue tracker. The Responsible Disclosure Program details the procedure for disclosing security issues.
+What is Auth0?
What is Auth0?
This project is licensed under the MIT license. See the LICENSE file for more info.
-
Error class representing an access token for connection error. +
Class AccessTokenForConnectionError
Error class representing an access token for connection error. Extends the
-SdkErrorclass.Hierarchy (View Summary)
Index
Constructors
Hierarchy (View Summary)
Index
Constructors
Properties
Constructors
constructor
    code: string,
    message: string,
    cause?: OAuth2Error,
): AccessTokenForConnectionError
Constructs a new
AccessTokenForConnectionErrorinstance.Parameters
The error code.
The error message.
Optionalcause: OAuth2ErrorThe OAuth2 cause of the error.
-Returns AccessTokenForConnectionError
Properties
Optionalcausecode
The error code associated with the access token error.
-Settings
On This Page
Constructors
Properties
Returns AccessTokenForConnectionError