Installation

Install the Auth0 Next.js SDK and configure your environment

Prerequisites

Before installing the Auth0 Next.js SDK, ensure you have:

• Node.js 20 LTS or newer LTS version
• A Next.js application (version 14.2.35 or later)
• An Auth0 account and application

The SDK supports Next.js 14, 15, and 16, with both the App Router and Pages Router.

Install the SDK

Install the @auth0/nextjs-auth0 package using your preferred package manager:

npm

npm install @auth0/nextjs-auth0

Configure Environment Variables

Create a .env.local file in the root of your project and add the following environment variables:

.env.local

AUTH0_DOMAIN=your-tenant.us.auth0.com
AUTH0_CLIENT_ID=your_client_id
AUTH0_CLIENT_SECRET=your_client_secret
AUTH0_SECRET=use_a_long_secret_value_at_least_32_characters_long
APP_BASE_URL=http://localhost:3000

Required Variables

AUTH0_DOMAIN · string · required

Your Auth0 tenant domain (e.g., example.us.auth0.com or https://example.us.auth0.com). Find this in your Auth0 Dashboard under your application settings.

AUTH0_CLIENT_ID · string · required

Your Auth0 application’s client ID. This can be found in the Auth0 Dashboard when you create a Regular Web Application.

AUTH0_CLIENT_SECRET · string · required

Your Auth0 application’s client secret. This is shown in the Auth0 Dashboard alongside the client ID.

AUTH0_SECRET · string · required

A 32-byte, hex-encoded secret used for encrypting session cookies. Generate one using:

openssl rand -hex 32

Keep this secret secure and never commit it to version control. Use different secrets for different environments.

APP_BASE_URL · string

The URL where your application is running. For local development, this is typically http://localhost:3000. For production, use your production URL.

You can omit APP_BASE_URL to let the SDK infer it from the request host at runtime. This is useful for preview deployments on platforms like Vercel or Netlify.

Configure Auth0 Application Settings

In your Auth0 Dashboard, configure your application with the following URLs:

1. Create a Regular Web Application

   If you haven’t already, create a new application and select Regular Web Application as the application type.

2. Add Callback URLs

   Add your callback URL to the Allowed Callback URLs field:

   http://localhost:3000/auth/callback
   

   For production, add your production callback URL:

   https://yourapp.com/auth/callback
   
3. Add Logout URLs

   Add your logout URL to the Allowed Logout URLs field:

   http://localhost:3000
   

   For production:

   https://yourapp.com
   

When using dynamic preview environments (Vercel, Netlify), ensure each preview URL is registered in your Auth0 application, or configure wildcard URLs if supported by your Auth0 plan.

Dynamic Base URLs (Preview Deployments)

For preview environments on platforms like Vercel or Netlify, you can omit the APP_BASE_URL environment variable. The SDK will automatically infer the base URL from the incoming request host.

Auth0’s Allowed Callback URLs serve as the security boundary. If the inferred host is not registered in your Auth0 application, Auth0 will reject the authorization request.

Static Base URL (Recommended for Production)

For production environments with a stable domain, explicitly set the APP_BASE_URL:

lib/auth0.ts

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

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

Dynamic Base URL (Preview Environments)

For dynamic preview URLs, omit the appBaseUrl configuration:

lib/auth0.ts

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

export const auth0 = new Auth0Client();

When relying on dynamic base URLs in production, the SDK enforces secure cookies. Setting AUTH0_COOKIE_SECURE=false will throw an InvalidConfigurationError.

Optional Environment Variables

You can configure additional behavior using these optional environment variables:

.env.local

# Cookie configuration
AUTH0_COOKIE_DOMAIN=.example.com
AUTH0_COOKIE_PATH=/
AUTH0_COOKIE_TRANSIENT=false
AUTH0_COOKIE_SECURE=true
AUTH0_COOKIE_SAME_SITE=lax

# DPoP (Demonstrating Proof-of-Possession)
AUTH0_DPOP_PUBLIC_KEY=-----BEGIN PUBLIC KEY-----\n...
AUTH0_DPOP_PRIVATE_KEY=-----BEGIN PRIVATE KEY-----\n...
AUTH0_DPOP_CLOCK_SKEW=0
AUTH0_DPOP_CLOCK_TOLERANCE=30

Base Path Configuration

If your Next.js application uses a base path (configured via basePath in next.config.js), set the NEXT_PUBLIC_BASE_PATH environment variable:

.env.local

NEXT_PUBLIC_BASE_PATH=/dashboard

This will mount authentication routes at /dashboard/auth/login, /dashboard/auth/callback, etc.

Do not use NEXT_PUBLIC_BASE_PATH with an APP_BASE_URL that contains a path component. Set APP_BASE_URL to the root URL (e.g., https://example.com) and use NEXT_PUBLIC_BASE_PATH for the base path.

Verify Installation

To verify your installation is working correctly, you can check that the SDK can be imported:

Server-side

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

const auth0 = new Auth0Client();

Next Steps

Now that you’ve installed and configured the SDK, proceed to the Quickstart to implement authentication in your Next.js application.