Auth0Client

Configure the Auth0 client for server-side authentication

The Auth0Client class is the main entry point for server-side authentication in your Next.js application.

Constructor

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

const auth0 = new Auth0Client(options);

Configuration Options

Required Options

These options can be provided via 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 client ID for your application.

Environment variable: AUTH0_CLIENT_ID

clientSecret · string

The Auth0 client secret for your application.

Environment variable: AUTH0_CLIENT_SECRET

Either clientSecret or clientAssertionSigningKey must be provided.

secret · string

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

Environment variable: AUTH0_SECRET

Generate with:

openssl rand -hex 32

Application Configuration

appBaseUrl · string | string[]

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

Can be a single URL string, or an array of allowed base URLs for multi-domain deployments.

Environment variable: APP_BASE_URL (comma-separated for multiple origins)

If omitted, the SDK infers the base URL from the request host at runtime.

signInReturnToPath · string · default: "/"

The path to redirect users to after successful authentication.

Authorization Parameters

authorizationParameters · object

Additional parameters sent to the /authorize endpoint.

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

Common parameters:

• scope: OAuth scopes to request
• audience: API identifier for access token
• connection: Specific connection to use
• prompt: Force authentication prompt

pushedAuthorizationRequests · boolean · default: false

Enable Pushed Authorization Requests (PAR) for enhanced security.

Session Configuration

session · SessionConfiguration

Configure session timeouts and rolling behavior.

session: {
  rolling: true,
  absoluteDuration: 60 * 60 * 24 * 7, // 7 days
  inactivityDuration: 60 * 60 * 24,   // 1 day
  cookie: {
    name: '__session',
    secure: true,
    sameSite: 'lax',
    path: '/',
    domain: '.example.com',
    transient: false
  }
}

Session Options

• rolling (boolean, default: true): Enable rolling sessions
• absoluteDuration (number, default: 259200): Absolute session lifetime in seconds (3 days)
• inactivityDuration (number, default: 86400): Inactivity timeout in seconds (1 day)
• cookie.name (string, default: __session): Cookie name
• cookie.secure (boolean): Force HTTPS-only cookies
• cookie.sameSite (‘lax’ | ‘strict’ | ‘none’, default: ‘lax’)
• cookie.path (string, default: ’/’)
• cookie.domain (string): Cookie domain
• cookie.transient (boolean, default: false): Session-only cookie

sessionStore · SessionDataStore

Custom session store implementation for database-backed sessions.

See Session Stores for implementation 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 RP-Initiated Logout
• v2: Always uses Auth0’s /v2/logout endpoint (supports wildcards)

includeIdTokenHintInOIDCLogoutUrl · boolean · default: true

Include id_token_hint parameter in OIDC logout URLs.

When set to false, logout requests lose cryptographic verification. Only disable if privacy requirements outweigh DoS protection concerns.

Token Configuration

tokenRefreshBuffer · number · default: 0

Number of seconds to refresh access tokens early before expiration.

tokenRefreshBuffer: 60 // Refresh tokens 60 seconds before expiry

enableAccessTokenEndpoint · boolean · default: true

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

Set to false for Token Mediating Backend pattern where clients don’t need direct token access.

Hooks

beforeSessionSaved · function

Manipulate the session before persisting it.

beforeSessionSaved: async (session) => {
  // Remove sensitive claims
  delete session.user.phone_number;
  return session;
}

onCallback · function

Handle errors or manage redirects after authentication callback.

onCallback: async (req, session) => {
  // Custom redirect logic
  return session.user.isAdmin ? '/admin' : '/dashboard';
}

Advanced Options

clientAssertionSigningKey · string | CryptoKey

Private key for private_key_jwt client authentication.

Environment variable: AUTH0_CLIENT_ASSERTION_SIGNING_KEY

clientAssertionSigningAlg · string

Algorithm for signing client assertion JWT.

Environment variable: AUTH0_CLIENT_ASSERTION_SIGNING_ALG

routes · RoutesOptions

Customize authentication route paths.

routes: {
  login: '/api/auth/login',
  callback: '/api/auth/callback',
  logout: '/api/auth/logout'
}

httpTimeout · number · default: 5000

HTTP timeout in milliseconds for authentication requests.

enableTelemetry · boolean · default: true

Send SDK name and version via Auth0-Client header.

allowInsecureRequests · boolean · default: false

Allow HTTP requests to authorization server (development only).

Only works when NODE_ENV is not production.

noContentProfileResponseWhenUnauthenticated · boolean · default: false

Return 204 No Content instead of 401 Unauthorized from /auth/profile when unauthenticated.

enableConnectAccountEndpoint · boolean · default: false

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

Transaction Cookie Configuration

transactionCookie · TransactionCookieOptions

Configure transaction cookie for authentication flows.

transactionCookie: {
  prefix: '__txn_',
  secure: true,
  sameSite: 'lax',
  path: '/',
  maxAge: 3600
}

enableParallelTransactions · boolean · default: true

Support multiple concurrent authentication flows with unique transaction cookies.

DPoP Configuration

useDPoP · boolean · default: false

Enable DPoP (Demonstrating Proof-of-Possession) for enhanced OAuth 2.0 security.

Requires ES256 key pair via dpopKeyPair or environment variables.

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

Environment variables:

• AUTH0_DPOP_PUBLIC_KEY: PEM-encoded public key
• AUTH0_DPOP_PRIVATE_KEY: PEM-encoded private key

dpopOptions · DpopOptions

Configure DPoP timing validation and retry behavior.

dpopOptions: {
  clockTolerance: 60,
  clockSkew: 0,
  retry: {
    delay: 200,
    jitter: true
  }
}

MFA Configuration

mfaTokenTtl · number · default: 300

MFA context TTL in seconds (5 minutes by default).

Environment variable: AUTH0_MFA_TOKEN_TTL

Example Configurations

Basic Configuration

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

export const auth0 = new Auth0Client({
  domain: process.env.AUTH0_DOMAIN!,
  clientId: process.env.AUTH0_CLIENT_ID!,
  clientSecret: process.env.AUTH0_CLIENT_SECRET!,
  secret: process.env.AUTH0_SECRET!,
  appBaseUrl: process.env.APP_BASE_URL,
  authorizationParameters: {
    scope: 'openid profile email',
    audience: 'https://api.example.com'
  }
});

Methods

See the following pages for detailed method documentation:

getSession

Retrieve session data

getAccessToken

Get access tokens

updateSession

Update session data

withPageAuthRequired

Protect pages