Configuration

Auth0Client configuration options for initializing the SDK

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_SECRET

Generate 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.

signInReturnToPath · string · default: "/"

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

See Also

• SessionData - Session data structure
• User - User profile interface
• TokenSet - Token structure