Configuration

The Auth0Client can be customized using configuration options passed to the constructor or via environment variables.

Basic Setup

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

export const auth0 = new Auth0Client({
  domain: "example.us.auth0.com",
  clientId: "your-client-id",
  clientSecret: "your-client-secret",
  secret: "your-32-char-secret",
  appBaseUrl: "https://app.example.com"
});

Required Configuration

domain

string

The Auth0 domain for your tenant (e.g., example.us.auth0.com or https://example.us.auth0.com).Environment variable: AUTH0_DOMAIN

clientId

string

The Auth0 client ID for your application.Environment variable: AUTH0_CLIENT_ID

secret

string

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

openssl rand -hex 32

Environment variable: AUTH0_SECRET

clientSecret

string

The Auth0 client secret. Required unless using clientAssertionSigningKey.Environment variable: AUTH0_CLIENT_SECRET

Optional Configuration

Application Settings

appBaseUrl

string

The URL of your application (e.g., http://localhost:3000).If omitted, the SDK will infer it from the request host at runtime. This is useful for dynamic preview environments (Vercel, Netlify).Environment variable: APP_BASE_URLSecurity note: When using dynamic base URLs in production, the SDK enforces secure cookies. Explicitly setting secure=false will throw InvalidConfigurationError.

The path to redirect users to after successful authentication.

enableTelemetry

boolean

default:"true"

Send library name and version to your authorization server via the Auth0-Client header.

httpTimeout

number

default:"5000"

HTTP timeout in milliseconds for authentication requests.

allowInsecureRequests

boolean

default:"false"

Allow insecure requests to the authorization server (useful for testing with mock OIDC providers).Note: Can only be used when NODE_ENV is not set to production.

Authorization Parameters

authorizationParameters

AuthorizationParameters

Authorization parameters to pass to the /authorize endpoint.

{
  authorizationParameters: {
    audience: "https://api.example.com",
    scope: "openid profile email read:posts"
  }
}

See Passing authorization parameters for more details.

Logout Configuration

logoutStrategy

'auto' | 'oidc' | 'v2'

default:"auto"

Strategy for logout endpoint selection:

auto: 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 Configuring logout strategy for details.

includeIdTokenHintInOIDCLogoutUrl

boolean

default:"true"

Configure whether to include id_token_hint in OIDC logout URLs.

true (recommended): Includes ID token for better DoS protection
false: Excludes PII from logout URLs but reduces DoS protection

See OIDC logout privacy configuration for details.

Session Configuration

session

SessionConfiguration

Configure session timeouts, rolling sessions, and cookie attributes.

{
  session: {
    rolling: true,
    rollingDuration: 86400, // 24 hours
    absoluteDuration: 604800, // 7 days
    cookie: {
      domain: ".example.com",
      path: "/",
      transient: false,
      secure: true,
      sameSite: "lax"
    }
  }
}

Cookie environment variables:

AUTH0_COOKIE_DOMAIN
AUTH0_COOKIE_PATH
AUTH0_COOKIE_TRANSIENT
AUTH0_COOKIE_SECURE
AUTH0_COOKIE_SAME_SITE

Note: httpOnly is always true for security.See Session Configuration and Cookie Configuration for details.

sessionStore

SessionStore

Custom session store implementation for persisting sessions to an external data store.See Database sessions for details.

Transaction Cookies

enableParallelTransactions

boolean

default:"true"

Enable support for multiple concurrent authentication flows.

true: Each authentication attempt gets its own transaction cookie with a unique state suffix
false: Uses a single shared transaction cookie (may cause conflicts with concurrent auth attempts)

See Transaction Cookie Configuration for details.

Configure transaction cookie management for authentication flows.

{
  transactionCookie: {
    duration: 600, // 10 minutes
    secure: true,
    sameSite: "lax"
  }
}

See Transaction Cookie Configuration for details.

Advanced OAuth

clientAssertionSigningKey

string | CryptoKey

Private key for use with private_key_jwt clients.Environment variable: AUTH0_CLIENT_ASSERTION_SIGNING_KEY

clientAssertionSigningAlg

string

The algorithm used to sign the client assertion JWT.Environment variable: AUTH0_CLIENT_ASSERTION_SIGNING_ALG

pushedAuthorizationRequests

boolean

default:"false"

Configure the SDK to use Pushed Authorization Requests (PAR) protocol when communicating with the authorization server.

DPoP (Demonstrating Proof-of-Possession)

useDPoP

boolean

default:"false"

Enable DPoP for enhanced security. When enabled, the client will generate DPoP proofs for token requests and protected resource requests.DPoP binds access tokens to cryptographic key pairs, preventing token theft and replay attacks.

dpopKeyPair

DpopKeyPair

ES256 key pair for DPoP proof generation.

import { generateKeyPair } from "oauth4webapi";

const dpopKeyPair = await generateKeyPair("ES256");

const auth0 = new Auth0Client({
  useDPoP: true,
  dpopKeyPair
});

If not provided, the SDK will attempt to load keys from environment variables:

AUTH0_DPOP_PUBLIC_KEY (PEM format)
AUTH0_DPOP_PRIVATE_KEY (PEM format)

dpopOptions

DpopOptions

Configure DPoP timing validation to handle clock differences between client and server.

{
  dpopOptions: {
    clockSkew: 120,      // Adjust for local clock being 2 minutes behind
    clockTolerance: 45   // Allow 45 seconds tolerance for validation
  }
}

Environment variables:

AUTH0_DPOP_CLOCK_SKEW: Clock adjustment in seconds
AUTH0_DPOP_CLOCK_TOLERANCE: Tolerance in seconds

See DPoP Clock Validation for details.

Custom Routes

routes

Routes

Configure the paths for authentication routes.

{
  routes: {
    login: "/custom-login",
    logout: "/custom-logout",
    callback: "/custom-callback",
    profile: "/custom-profile",
    accessToken: "/custom-access-token",
    backchannelLogout: "/custom-backchannel-logout"
  }
}

See Custom routes for details.

Hooks

beforeSessionSaved

BeforeSessionSavedHook

A method to manipulate the session before persisting it.

{
  beforeSessionSaved: async (session) => {
    session.user.customClaim = "value";
    return session;
  }
}

See beforeSessionSaved for details.

onCallback

OnCallbackHook

A method to handle errors or manage redirects after attempting to authenticate.

{
  onCallback: async (req, session, state) => {
    return {
      redirectTo: state?.returnTo || "/dashboard"
    };
  }
}

See onCallback for details.

Access Token Configuration

enableAccessTokenEndpoint

boolean

default:"true"

Enable the /auth/access-token endpoint for client-side access token retrieval.Disable this if you don’t need access tokens on the client-side.

tokenRefreshBuffer

number

default:"0"

Refresh access tokens this many seconds before they expire.Useful for ensuring tokens don’t expire mid-request.

Base Path Configuration

NEXT_PUBLIC_BASE_PATH

string

Set this environment variable when your Next.js application uses a base path (configured via basePath in next.config.js).Example: If set to /dashboard, authentication routes will be mounted at:

/dashboard/auth/login
/dashboard/auth/callback
/dashboard/auth/logout

Note: 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 and use NEXT_PUBLIC_BASE_PATH for the base path.

Configuration Validation

The SDK validates required configuration options when initializing the Auth0Client. Missing required options will result in a warning with details on how to provide them. Required options:

domain or AUTH0_DOMAIN
clientId or AUTH0_CLIENT_ID
secret or AUTH0_SECRET
Either:
- clientSecret or AUTH0_CLIENT_SECRET, OR
- clientAssertionSigningKey or AUTH0_CLIENT_ASSERTION_SIGNING_KEY

Optional:

appBaseUrl or APP_BASE_URL (inferred from request if omitted)

Environment Variables Summary

Variable	Description	Required
`AUTH0_DOMAIN`	Auth0 tenant domain	Yes
`AUTH0_CLIENT_ID`	Application client ID	Yes
`AUTH0_CLIENT_SECRET`	Application client secret	Yes*
`AUTH0_SECRET`	Session encryption key (32 chars min)	Yes
`APP_BASE_URL`	Application base URL	No**
`AUTH0_CLIENT_ASSERTION_SIGNING_KEY`	Private key for `private_key_jwt`	No
`AUTH0_CLIENT_ASSERTION_SIGNING_ALG`	Client assertion signing algorithm	No
`AUTH0_COOKIE_DOMAIN`	Cookie domain	No
`AUTH0_COOKIE_PATH`	Cookie path	No
`AUTH0_COOKIE_TRANSIENT`	Transient cookie flag	No
`AUTH0_COOKIE_SECURE`	Secure cookie flag	No
`AUTH0_COOKIE_SAME_SITE`	SameSite cookie attribute	No
`AUTH0_DPOP_PUBLIC_KEY`	DPoP public key (PEM)	No
`AUTH0_DPOP_PRIVATE_KEY`	DPoP private key (PEM)	No
`AUTH0_DPOP_CLOCK_SKEW`	DPoP clock adjustment (seconds)	No
`AUTH0_DPOP_CLOCK_TOLERANCE`	DPoP validation tolerance (seconds)	No
`NEXT_PUBLIC_BASE_PATH`	Next.js base path	No

* Required unless using AUTH0_CLIENT_ASSERTION_SIGNING_KEY ** Inferred from request host if omitted

Get Started

Core Concepts

Client API

Server API

Guides

Advanced Features

Migration

Resources

Basic Setup

Required Configuration

Optional Configuration

Application Settings

Authorization Parameters

Logout Configuration

Session Configuration

Transaction Cookies

Advanced OAuth

DPoP (Demonstrating Proof-of-Possession)

Custom Routes

Hooks

Access Token Configuration

Base Path Configuration

Configuration Validation

Environment Variables Summary

Build docs developers (and LLMs) love

Get Started

Core Concepts

Client API

Server API

Guides

Advanced Features

Migration

Resources

​Basic Setup

​Required Configuration

​Optional Configuration

​Application Settings

​Authorization Parameters

​Logout Configuration

​Session Configuration

​Transaction Cookies

​Advanced OAuth

​DPoP (Demonstrating Proof-of-Possession)

​Custom Routes

​Hooks

​Access Token Configuration

​Base Path Configuration

​Configuration Validation

​Environment Variables Summary

Build docs developers (and LLMs) love

Basic Setup

Required Configuration

Optional Configuration

Application Settings

Authorization Parameters

Logout Configuration

Session Configuration

Transaction Cookies

Advanced OAuth

DPoP (Demonstrating Proof-of-Possession)

Custom Routes

Hooks

Access Token Configuration

Base Path Configuration

Configuration Validation

Environment Variables Summary