Skip to main content
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_SECRETGenerate 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
  }
}
  • 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.
​
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

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

Build docs developers (and LLMs) love

Get started for freeTalk to us