Configuration

Overview

The Auth0ClientOptions interface defines all configuration options available when creating an Auth0Client instance. These options control authentication behavior, session management, token handling, and security features.

Type Definition

export interface Auth0ClientOptions {
  // Authorization server configuration
  domain?: string;
  clientId?: string;
  clientSecret?: string;
  authorizationParameters?: AuthorizationParameters;
  pushedAuthorizationRequests?: boolean;
  clientAssertionSigningKey?: string | CryptoKey;
  clientAssertionSigningAlg?: string;
  
  // Application configuration
  appBaseUrl?: string | string[];
  secret?: string;
  signInReturnToPath?: string;
  
  // Session configuration
  session?: SessionConfiguration;
  
  // Transaction cookie configuration
  transactionCookie?: TransactionCookieOptions;
  
  // Logout configuration
  logoutStrategy?: LogoutStrategy;
  includeIdTokenHintInOIDCLogoutUrl?: boolean;
  
  // Hooks
  beforeSessionSaved?: BeforeSessionSavedHook;
  onCallback?: OnCallbackHook;
  
  // Session store
  sessionStore?: SessionDataStore;
  
  // Routes
  routes?: RoutesOptions;
  
  // Security and networking
  allowInsecureRequests?: boolean;
  httpTimeout?: number;
  enableTelemetry?: boolean;
  enableAccessTokenEndpoint?: boolean;
  tokenRefreshBuffer?: number;
  noContentProfileResponseWhenUnauthenticated?: boolean;
  enableParallelTransactions?: boolean;
  enableConnectAccountEndpoint?: boolean;
  
  // DPoP configuration
  useDPoP?: boolean;
  dpopKeyPair?: DpopKeyPair;
  dpopOptions?: DpopOptions;
  
  // MFA configuration
  mfaTokenTtl?: number;
}

Required Configuration

These options must be provided either through the constructor or environment variables:

domain

string

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

clientId

string

The Auth0 application client ID.Environment variable: AUTH0_CLIENT_ID

clientSecret

string

The Auth0 application client secret. Either this or clientAssertionSigningKey must be provided.Environment variable: AUTH0_CLIENT_SECRET

secret

string

A 32-byte, hex-encoded secret used for encrypting session cookies.Environment variable: AUTH0_SECRETGenerate with: openssl rand -hex 32

Authorization Server Options

authorizationParameters

AuthorizationParameters

Additional parameters to send to the /authorize endpoint. See AuthorizationParameters below.

pushedAuthorizationRequests

boolean

default:false

Enable Pushed Authorization Requests (PAR) for enhanced security.

clientAssertionSigningKey

string | CryptoKey

Private key for use with private_key_jwt client authentication. Can be a PEM string or CryptoKey.Environment variable: AUTH0_CLIENT_ASSERTION_SIGNING_KEY

clientAssertionSigningAlg

string

Algorithm used to sign client assertion JWT (e.g., “RS256”, “ES256”).Environment variable: AUTH0_CLIENT_ASSERTION_SIGNING_ALG

Application Options

appBaseUrl

string | string[]

The base URL(s) of your application (e.g., http://localhost:3000).

Single URL: "https://app.example.com"
Multiple URLs: ["https://app.example.com", "https://myapp.vercel.app"]
Environment variable: APP_BASE_URL (comma-separated for multiple)

If not provided, the SDK infers from the request host at runtime.

Path to redirect users to after successful authentication.

Session Options

session

SessionConfiguration

Configure session timeouts and behavior.

interface SessionConfiguration {
  rolling?: boolean;              // Default: true
  absoluteDuration?: number;      // Default: 259200 (3 days)
  inactivityDuration?: number;    // Default: 86400 (1 day)
  cookie?: SessionCookieOptions;
}

Show Session Cookie Options

interface SessionCookieOptions {
  name?: string;           // Default: "__session"
  sameSite?: "strict" | "lax" | "none";  // Default: "lax"
  secure?: boolean;        // Auto-detected from appBaseUrl
  path?: string;           // Default: "/"
  domain?: string;
  transient?: boolean;     // Don't persist beyond session
}

sessionStore

SessionDataStore

Custom session store implementation for database-backed sessions.

interface SessionDataStore {
  get(id: string): Promise<SessionData | null>;
  set(id: string, session: SessionData): Promise<void>;
  delete(id: string): Promise<void>;
  deleteByLogoutToken?(logoutToken: LogoutToken): Promise<void>;
}

Logout Options

logoutStrategy

'auto' | 'oidc' | 'v2'

default:"auto"

Logout endpoint selection strategy:

auto - Try OIDC RP-Initiated Logout, fallback to /v2/logout
oidc - Always use OIDC RP-Initiated Logout
v2 - Always use Auth0 /v2/logout endpoint

includeIdTokenHintInOIDCLogoutUrl

boolean

default:true

Include id_token_hint parameter in OIDC logout URLs. Recommended for security.

Hooks

beforeSessionSaved

BeforeSessionSavedHook

Callback to modify the session before it’s persisted.

type BeforeSessionSavedHook = (
  session: SessionData,
  idToken?: string
) => SessionData | Promise<SessionData>;

Example:

beforeSessionSaved: async (session, idToken) => {
  return {
    ...session,
    user: {
      ...session.user,
      customField: 'value'
    }
  };
}

onCallback

OnCallbackHook

Callback to handle post-authentication logic or customize redirects.

type OnCallbackHook = (
  context: OnCallbackContext
) => void | { returnTo: string } | Promise<void | { returnTo: string }>;

Example:

onCallback: async (context) => {
  const { session, request } = context;
  
  // Redirect to profile page for new users
  if (session.user.isNewUser) {
    return { returnTo: '/profile/setup' };
  }
}

Token Options

tokenRefreshBuffer

number

default:0

Number of seconds before token expiration to trigger automatic refresh.Example: With tokenRefreshBuffer: 60, tokens expiring within 60 seconds will be proactively refreshed.

enableAccessTokenEndpoint

boolean

default:true

Enable the /auth/access-token endpoint for client-side token access.

Set to false for Token Mediating Backend pattern (recommended for most apps).

DPoP Configuration

useDPoP

boolean

default:false

Enable DPoP (Demonstrating Proof-of-Possession) for cryptographically bound tokens.Example:

import { generateKeyPair } from 'oauth4webapi';

const dpopKeyPair = await generateKeyPair('ES256');

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

dpopKeyPair

DpopKeyPair

ES256 key pair for DPoP proof generation.

interface DpopKeyPair {
  publicKey: CryptoKey;
  privateKey: CryptoKey;
}

Can be loaded from environment variables:

AUTH0_DPOP_PUBLIC_KEY
AUTH0_DPOP_PRIVATE_KEY

dpopOptions

DpopOptions

DPoP timing and retry configuration.

interface DpopOptions {
  clockTolerance?: number;  // Clock skew tolerance (seconds)
  clockSkew?: number;       // Clock adjustment (seconds)
  retry?: {
    delay?: number;         // Retry delay (ms)
    jitter?: boolean;       // Add random jitter
  };
}

MFA Configuration

mfaTokenTtl

number

default:300

MFA context TTL in seconds. Controls how long encrypted mfa_token remains valid.Environment variable: AUTH0_MFA_TOKEN_TTL

Route Configuration

routes

RoutesOptions

Customize authentication route paths.

interface RoutesOptions {
  login?: string;              // Default: "/auth/login"
  logout?: string;             // Default: "/auth/logout"
  callback?: string;           // Default: "/auth/callback"
  profile?: string;            // Default: "/auth/profile"
  accessToken?: string;        // Default: "/auth/access-token"
  connectAccount?: string;     // Default: "/auth/connect"
  backChannelLogout?: string;  // Default: "/auth/backchannel-logout"
}

Environment variables:

NEXT_PUBLIC_LOGIN_ROUTE
NEXT_PUBLIC_PROFILE_ROUTE
NEXT_PUBLIC_ACCESS_TOKEN_ROUTE

enableConnectAccountEndpoint

boolean

default:false

Enable the /auth/connect endpoint for connecting additional accounts.

Network and Security

allowInsecureRequests

boolean

default:false

Allow HTTP requests to authorization server. Only for testing with mock OIDC providers. Cannot be used in production.

httpTimeout

number

default:5000

HTTP timeout in milliseconds for authentication requests.

enableTelemetry

boolean

default:true

Send library name and version to Auth0 via Auth0-Client header.

enableParallelTransactions

boolean

default:true

Allow multiple concurrent authentication transactions.

noContentProfileResponseWhenUnauthenticated

boolean

default:false

Return 204 No Content instead of 401 Unauthorized for unauthenticated profile endpoint requests.

AuthorizationParameters

export interface AuthorizationParameters {
  scope?: string | null;
  audience?: string | null;
  redirect_uri?: string | null;
  max_age?: number;
  organization?: string;
  [key: string]: unknown;
}

scope

string

default:"openid profile email offline_access"

OAuth scopes to request. Space-delimited string.

audience

string

API identifier for the target resource server.

redirect_uri

string

Override the redirect URI for the callback.

max_age

number

Maximum authentication age in seconds. Forces re-authentication if exceeded.

organization

string

Organization ID for organization-specific login.

Usage Example

import { Auth0Client } from '@auth0/nextjs-auth0/server';
import { generateKeyPair } from 'oauth4webapi';

const dpopKeyPair = await generateKeyPair('ES256');

export const auth0 = new Auth0Client({
  // Required (or via env vars)
  domain: 'example.us.auth0.com',
  clientId: 'abc123',
  clientSecret: 'secret123',
  secret: '0123456789abcdef0123456789abcdef',
  appBaseUrl: 'https://myapp.com',
  
  // Authorization
  authorizationParameters: {
    scope: 'openid profile email offline_access',
    audience: 'https://api.example.com'
  },
  
  // Session
  session: {
    rolling: true,
    absoluteDuration: 7 * 24 * 60 * 60, // 7 days
    inactivityDuration: 24 * 60 * 60,   // 1 day
    cookie: {
      name: 'app_session',
      sameSite: 'lax',
      secure: true
    }
  },
  
  // Token management
  tokenRefreshBuffer: 60,
  enableAccessTokenEndpoint: false,
  
  // DPoP
  useDPoP: true,
  dpopKeyPair,
  
  // Hooks
  beforeSessionSaved: async (session) => {
    return {
      ...session,
      user: {
        ...session.user,
        displayName: session.user.name || session.user.email
      }
    };
  },
  
  // Routes
  routes: {
    login: '/api/auth/login',
    callback: '/api/auth/callback'
  }
});

Client

Server

Errors

Types

Overview

Type Definition

Required Configuration

Authorization Server Options

Application Options

Session Options

Logout Options

Hooks

Token Options

DPoP Configuration

MFA Configuration

Route Configuration

Network and Security

AuthorizationParameters

Usage Example

See Also

Build docs developers (and LLMs) love

Client

Server

Errors

Types

​Overview

​Type Definition

​Required Configuration

​Authorization Server Options

​Application Options

​Session Options

​Logout Options

​Hooks

​Token Options

​DPoP Configuration

​MFA Configuration

​Route Configuration

​Network and Security

​AuthorizationParameters

​Usage Example

​See Also

Build docs developers (and LLMs) love

Overview

Type Definition

Required Configuration

Authorization Server Options

Application Options

Session Options

Logout Options

Hooks

Token Options

DPoP Configuration

MFA Configuration

Route Configuration

Network and Security

AuthorizationParameters

Usage Example

See Also