Configuration

Complete reference for all Auth0Client configuration options

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_URL

Security note: When using dynamic base URLs in production, the SDK enforces secure cookies. Explicitly setting secure=false will throw InvalidConfigurationError.

signInReturnToPath · string · default: "/"

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.

transactionCookie · TransactionCookieOptions

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