nextjs-auth0

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.
• Anonymous Sessions - enable pre-login identity with access tokens and metadata.
• Security - Some important security notices that you should check.
• Docs Site - explore our docs site and learn more about 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:

AUTH0_DOMAIN=
AUTH0_CLIENT_ID=
AUTH0_CLIENT_SECRET=
AUTH0_SECRET=
APP_BASE_URL= # optional for dynamic preview environments

The AUTH0_DOMAIN, AUTH0_CLIENT_ID, and AUTH0_CLIENT_SECRET can be obtained from the Auth0 Dashboard once you've created an application. This application must be a Regular Web Application.

The AUTH0_SECRET is the key used to encrypt the session and transaction cookies. You can generate a secret using openssl:

openssl rand -hex 32

The APP_BASE_URL is the URL that your application is running on. When developing locally, this is most commonly http://localhost:3000. If you omit it, the SDK will infer the base URL from the incoming request host at runtime.

[!IMPORTANT]
You will need to register the following URLs in your Auth0 Application via the Auth0 Dashboard:

• Add http://localhost:3000/auth/callback to the list of Allowed Callback URLs
• Add http://localhost:3000 to the list of Allowed Logout URLs

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.

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):

import { Auth0Client } from "@auth0/nextjs-auth0/server";

export const auth0 = new Auth0Client();

Example (static):

import { Auth0Client } from "@auth0/nextjs-auth0/server";

export const auth0 = new Auth0Client({
  appBaseUrl: "https://app.example.com"
});

[!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

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();

[!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

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:

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).*)"
  ]
};

[!NOTE]
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. 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):

import { auth0 } from "./lib/auth0";

export async function proxy(request: Request) { // Note that proxy uses the standard Request type
  return await auth0.middleware(request);
}

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

[!IMPORTANT]
Starting with Next.js 16, the recommended file for handling authentication boundaries is proxy.ts. You can still continue using middleware.ts for backward compatibility, it will work under the Edge runtime in Next.js 16. However, it is deprecated for the Node runtime and will be removed in a future release.

The new proxy layer also executes slightly earlier in the routing pipeline, so make sure your matcher patterns do not conflict with other proxy or middleware routes.

Additionally, the Edge runtime now applies stricter header and cookie validation,
so avoid setting non-string cookie values or invalid header formats.

[!IMPORTANT] This broad middleware matcher is essential for rolling sessions and security features. For scenarios when rolling sessions are disabled, see Session Configuration for alternative approaches.

You can now begin to authenticate your users by redirecting them to your application's /auth/login route:

import { auth0 } from "./lib/auth0"; // Adjust path if your auth0 client is elsewhere

export default async function Home() {
  const session = await auth0.getSession();

  if (!session) {
    return (
      <main>
        <a href="/auth/login?screen_hint=signup">Sign up</a>
        <a href="/auth/login">Log in</a>
      </main>
    );
  }

  return (
    <main>
      <h1>Welcome, {session.user.name}!</h1>
    </main>
  );
}

[!IMPORTANT]
A default <Link href="/auth/login"> is safe — the SDK detects the AUTO prefetch header and returns 204 No Content without writing a transaction cookie. Avoid <Link href="/auth/login" prefetch={true}> (FULL prefetch): it sends no detectable prefetch header, so the SDK cannot distinguish it from a real navigation and will start a login flow. Use a plain <a> tag or <Link prefetch={false}> if you need to be safe across all prefetch modes. See Preventing "431 Request Header Fields Too Large" Errors for details.

Customizing the client

You can customize the client by using the options below:

Option	Type	Description
domain	string | DomainResolver	The Auth0 domain for the tenant (e.g.: example.us.auth0.com). Accepts a static string or a DomainResolver function for Multiple Custom Domains. Falls back to AUTH0_DOMAIN environment variable.
clientId	string	The Auth0 client ID. If it's not specified, it will be loaded from the AUTH0_CLIENT_ID environment variable.
clientSecret	string	The Auth0 client secret. If it's not specified, it will be loaded from the AUTH0_CLIENT_SECRET environment variable.
authorizationParameters	AuthorizationParameters	The authorization parameters to pass to the /authorize endpoint. See Passing authorization parameters for more details.
clientAssertionSigningKey	string or CryptoKey	Private key for use with private_key_jwt clients. This can also be specified via the AUTH0_CLIENT_ASSERTION_SIGNING_KEY environment variable.
clientAssertionSigningAlg	string	The algorithm used to sign the client assertion JWT. This can also be provided via the AUTH0_CLIENT_ASSERTION_SIGNING_ALG environment variable.
appBaseUrl	string	The URL of your application (e.g.: http://localhost:3000). If it's not specified, it will be loaded from the APP_BASE_URL environment variable or inferred from the request host at runtime.
logoutStrategy	"auto" | "oidc" | "v2"	Strategy for logout endpoint selection. "auto" (default) uses OIDC logout when available, falls back to /v2/logout. "oidc" always uses OIDC logout. "v2" always uses /v2/logout endpoint which supports wildcard URLs. See for details.

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 onCallback hook to add custom logic after authentication completes

Additional customization options include:

• Login parameters via query parameters or static configuration
• Session data modification using the beforeSessionSaved hook
• Logout redirects using query parameters

[!IMPORTANT] 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:

AUTH0_COOKIE_DOMAIN=
AUTH0_COOKIE_PATH=
AUTH0_COOKIE_TRANSIENT=
AUTH0_COOKIE_SECURE=
AUTH0_COOKIE_SAME_SITE=
AUTH0_DPOP_PUBLIC_KEY=
AUTH0_DPOP_PRIVATE_KEY=
AUTH0_DPOP_CLOCK_SKEW=
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

# Enable DPoP and provide ES256 key pair
AUTH0_DPOP_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----
MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE...
-----END PUBLIC KEY-----"
AUTH0_DPOP_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----
MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQ...
-----END PRIVATE KEY-----"

import { Auth0Client } from "@auth0/nextjs-auth0/server";

export const auth0 = new Auth0Client({
  useDPoP: true
  // Keys loaded automatically from environment variables
});

Option 2: Programmatic Configuration

import { 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" })
});

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:

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
  }
});

Or configure via environment variables:

AUTH0_DPOP_CLOCK_SKEW=300        # Clock adjustment in seconds
AUTH0_DPOP_CLOCK_TOLERANCE=90    # Tolerance in seconds

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:

• 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:

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/`]: "read:me:profile update:me:profile",
      [`https://${process.env.AUTH0_DOMAIN}/my-org/`]: "org:read org:write"
    }
  }
});

Client-Side Usage

Make requests through the proxy paths:

// My Account API
const response = await fetch("/me/v1/profile", {
  headers: { "scope": "read:me:profile" }
});

// 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 and examples, see Proxy Handler for My Account and My Organization APIs. For My Account API examples, including managing the user's profile and integration with UI Components, see My Account API in guides/my-account.md.

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.

[!NOTE] 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:

• domain (or AUTH0_DOMAIN environment variable)
• clientId (or AUTH0_CLIENT_ID environment variable)
• secret (or AUTH0_SECRET environment variable)
• Either:
  • clientSecret (or AUTH0_CLIENT_SECRET environment variable), OR
  • clientAssertionSigningKey (or AUTH0_CLIENT_ASSERTION_SIGNING_KEY environment variable)

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:

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 following routes:

1. /auth/login: the login route that the user will be redirected to to initiate an authentication transaction
2. /auth/logout: the logout route that must be added to your Auth0 application's Allowed Logout URLs
3. /auth/callback: the callback route that must be added to your Auth0 application's Allowed Callback URLs
4. /auth/profile: the route to check the user's session and return their attributes
5. /auth/access-token: the route to check the user's session and return an access token (which will be automatically refreshed if a refresh token is available)
6. /auth/backchannel-logout: the route that will receive a logout_token when a configured Back-Channel Logout initiator occurs
7. /auth/connect: the route to connect an additional account to the current user's session
8. /auth/mfa/authenticators: the route to list the MFA authenticators enrolled for the current user
9. /auth/mfa/challenge: the route to initiate an MFA challenge for a specific authenticator
10. /auth/mfa/verify: the route to verify an MFA challenge response and step up the session
11. /auth/mfa/associate: the route to enroll a new MFA authenticator for the current user
12. /auth/passwordless/start: send an OTP code or magic link to a user's email or phone number
13. /auth/passwordless/verify: verify an OTP code and create a session
14. /auth/passwordless/otp/challenge: request an OTP for a database connection user (email or phone)
15. /auth/passwordless/otp/token: exchange an auth_session + OTP for tokens and create a session
16. /auth/passkey/register: get a WebAuthn credential creation challenge for a new user signup
17. /auth/passkey/challenge: get a WebAuthn credential assertion challenge for an existing user login
18. /auth/passkey/get-token: verify the WebAuthn credential and create a session

[!NOTE] The passwordless routes (/auth/passwordless/start and /auth/passwordless/verify) support Email OTP, SMS OTP, and Magic Link flows against dedicated passwordless connections. For magic links, the user clicks the emailed link and is redirected to /auth/callback — no separate verify step is needed. Magic links require the allow_magiclink_verify_without_session tenant flag. See Passwordless Authentication in EXAMPLES.md for full setup and usage details.

[!NOTE] The passwordless DB OTP routes (/auth/passwordless/otp/challenge and /auth/passwordless/otp/token) work with standard database connections configured with email_otp or phone_otp — not dedicated passwordless connections. Use passwordless.challengeWithEmail(), passwordless.challengeWithPhoneNumber(), and passwordless.loginWithOtp() from @auth0/nextjs-auth0/client. See Passwordless OTP on Database Connections in EXAMPLES.md for full setup and usage details.

[!NOTE] The passkey routes implement the WebAuthn ceremony server-side. Use the passkey singleton from @auth0/nextjs-auth0/client for the full one-call API (passkey.signup(), passkey.login()), or call each route individually for step-by-step control. See Passkey Authentication in guides/passkeys.md for full setup and usage details.

[!NOTE]
The /auth/access-token response includes token, expires_at (seconds since epoch), expires_in (TTL seconds), optional scope, and optional token_type. If you're using the client helper getAccessToken(), it returns only the token string by default; pass { includeFullResponse: true } to get the full response payload.

[!TIP]
You can refresh access tokens slightly before they expire by setting tokenRefreshBuffer (seconds) on the Auth0Client configuration.

[!IMPORTANT]
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.

Session Expiry from the Upstream IdP

For enterprise connections, the upstream identity provider can cap how long a user's session lives. When the connection is configured to honor it, Auth0 includes a session_expiry claim in the ID token (set via a Post-Login Action, value must be Unix seconds), and the SDK enforces this ceiling on every session read. Once it is reached, getSession() returns null, useUser() reflects the logged-out state, and getAccessToken() throws an AccessTokenError with code session_expired. If the ceiling is already in the past at login, the callback rejects the session immediately. Apps that assumed a session always exists after login should add a null check and redirect back to login.

For more details, see Session Expiry from the Upstream IdP in EXAMPLES.md.

Experiment Center

[!NOTE] Experiment Center support via SDKs is currently in Early Access. To request access to this feature, contact your Auth0 representative.

Experiment Center lets you A/B test your login flow. Force a specific variant by passing experiment_id and variation_id per-login, either as query params on /auth/login or via startInteractiveLogin:

<a href="/auth/login?experiment_id=<EXPERIMENT_ID>&variation_id=<VARIATION_ID>">
  Log in
</a>

For usage guidance, segment targeting, and testing patterns, see Experiment Center in guides/experiment-center.md.

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?