Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/auth0/nextjs-auth0/llms.txt

Use this file to discover all available pages before exploring further.

Configure how the SDK manages cookies for sessions and authentication transactions. The SDK uses two types of cookies: session cookies and transaction cookies. Session cookies store the encrypted user session. Configure session cookie attributes for security and functionality.

​
Using Environment Variables

Set cookie options via environment variables in your .env.local file:
.env.local
# Cookie Options
AUTH0_COOKIE_DOMAIN='.example.com'  # Set cookie for subdomains
AUTH0_COOKIE_PATH='/app'            # Limit cookie to /app path
AUTH0_COOKIE_TRANSIENT=false        # Make cookie persistent
AUTH0_COOKIE_SECURE=true            # Require HTTPS (recommended)
AUTH0_COOKIE_SAME_SITE='Lax'        # CSRF protection
The SDK automatically picks up these values at runtime.
The httpOnly attribute is always set to true for security and cannot be configured.

​
Using Auth0Client Options

Configure cookies programmatically when initializing the client:
lib/auth0.ts
import { Auth0Client } from "@auth0/nextjs-auth0/server";

export const auth0 = new Auth0Client({
  session: {
    cookie: {
      domain: ".example.com",
      path: "/app",
      transient: false,
      secure: process.env.NODE_ENV === "production",
      sameSite: "lax",
      name: "appSession" // Optional: custom cookie name
    }
  }
});
Options provided in Auth0ClientOptions take precedence over environment variables.
OptionTypeDefaultDescription
domainstringundefinedCookie domain (e.g., .example.com for subdomains)
pathstring/URL path where cookie is valid
transientbooleanfalseIf true, cookie expires when browser closes
securebooleanfalseIf true, cookie only sent over HTTPS
sameSite"lax" | "strict" | "none""lax"CSRF protection level
namestring"__session"Cookie name
httpOnlybooleantrueAlways true (not configurable)

​
Domain Configuration

Set the cookie domain to share sessions across subdomains: 
export const auth0 = new Auth0Client({
  session: {
    cookie: {
      domain: ".example.com" // Works for app.example.com, admin.example.com
    }
  }
});
Setting domain to a parent domain allows all subdomains to access the cookie. Only use this when you control all subdomains.

​
Path Configuration

Limit cookie scope to specific paths: 
export const auth0 = new Auth0Client({
  session: {
    cookie: {
      path: "/app" // Cookie only sent for /app/* routes
    }
  }
});

​
Transient Sessions

Create session-only cookies that expire when the browser closes: 
export const auth0 = new Auth0Client({
  session: {
    cookie: {
      transient: true // Cookie deleted when browser closes
    }
  }
});
Use cases:
  • Shared/public computers
  • Enhanced security requirements
  • Temporary sessions

​
Secure Cookies

Require HTTPS for cookie transmission: 
export const auth0 = new Auth0Client({
  session: {
    cookie: {
      secure: process.env.NODE_ENV === "production"
    }
  }
});
When appBaseUrl is omitted in production, the SDK automatically enforces secure: true. Attempting to set secure: false will throw an InvalidConfigurationError.

​
SameSite Configuration

Control when cookies are sent with cross-origin requests: 
export const auth0 = new Auth0Client({
  session: {
    cookie: {
      sameSite: "lax" // "lax", "strict", or "none"
    }
  }
});
Options:
ValueBehaviorUse Case
"lax"Sent on top-level navigation and same-site requestsRecommended - Balances security and usability
"strict"Only sent on same-site requestsHigh security, may break cross-origin flows
"none"Sent on all requests (requires secure: true)Cross-origin scenarios, embedded apps
Using sameSite: "none" requires secure: true and HTTPS. Browsers reject insecure cookies with SameSite=None.
Use a custom name for the session cookie: 
export const auth0 = new Auth0Client({
  session: {
    cookie: {
      name: "my_app_session" // Custom cookie name
    }
  }
});
Use cases:
  • Multiple Auth0 apps on same domain
  • Avoiding name conflicts
  • Custom naming conventions
Transaction cookies maintain state during authentication flows (OAuth state parameter). Configure transaction cookie behavior to prevent issues with concurrent logins.

​
Basic Configuration

lib/auth0.ts
import { Auth0Client } from "@auth0/nextjs-auth0/server";

export const auth0 = new Auth0Client({
  transactionCookie: {
    maxAge: 1800, // 30 minutes (in seconds)
    sameSite: "lax",
    secure: true,
    path: "/"
  }
});
OptionTypeDefaultDescription
maxAgenumber3600 (1 hour)Expiration time in seconds
prefixstring"__txn_"Cookie name prefix
sameSite"lax" | "strict" | "none""lax"CSRF protection
securebooleanDerived from appBaseUrlRequire HTTPS
pathstring/URL path

​
Transaction Management Modes

The SDK supports two transaction management modes:

​
Parallel Transactions (Default)

Allows multiple concurrent authentication flows: 
export const auth0 = new Auth0Client({
  enableParallelTransactions: true // Default
});
How it works:
  • Each login attempt gets a unique transaction cookie
  • Cookie named: __txn_{state}
  • Supports multiple tabs logging in simultaneously
  • Cookies cleaned up after successful authentication
Use when:
  • Users might open multiple tabs and log in simultaneously
  • You want maximum compatibility with typical user behavior
  • Your application supports multiple concurrent authentication flows

​
Single Transaction Mode

Only one active transaction at a time: 
export const auth0 = new Auth0Client({
  enableParallelTransactions: false
});
How it works:
  • Single transaction cookie: __txn_
  • New login attempts replace the previous transaction
  • Simpler cookie management
  • Prevents cookie accumulation
Use when:
  • You want to prevent cookie accumulation issues
  • You prefer simpler transaction management
  • Users typically don’t need multiple concurrent login flows
  • You’re experiencing cookie header size limits
Parallel transactions are recommended for most applications. Use single transaction mode only if you’re experiencing cookie-related issues or have specific requirements.
Customize the transaction cookie name prefix: 
export const auth0 = new Auth0Client({
  transactionCookie: {
    prefix: "auth_txn_" // Custom prefix
  }
});
Result:
  • Parallel mode: auth_txn_{state}
  • Single mode: auth_txn_
Control how long transaction cookies remain valid: 
export const auth0 = new Auth0Client({
  transactionCookie: {
    maxAge: 900 // 15 minutes
  }
});
Setting maxAge too low may cause authentication to fail if users take too long to complete the Auth0 login form.

​
Dynamic Preview Environments

For dynamic preview environments (Vercel, Netlify), you can omit APP_BASE_URL and let the SDK infer the base URL from the request:
lib/auth0.ts
import { Auth0Client } from "@auth0/nextjs-auth0/server";

// No appBaseUrl - inferred from request
export const auth0 = new Auth0Client();
Automatic enforcement:
  • In production, the SDK enforces secure: true for cookies
  • Attempting to set secure: false throws InvalidConfigurationError
  • Protects against misconfiguration in production
When using dynamic base URLs, ensure all possible callback and logout URLs are registered in your Auth0 Application settings. Auth0’s Allowed URLs act as a security safeguard.

​
Complete Configuration Example

lib/auth0.ts
import { Auth0Client } from "@auth0/nextjs-auth0/server";

export const auth0 = new Auth0Client({
  // Session configuration
  session: {
    rolling: true,
    absoluteDuration: 60 * 60 * 24 * 7, // 7 days
    inactivityDuration: 60 * 60 * 24,    // 1 day

    // Session cookie configuration
    cookie: {
      name: "app_session",
      domain: process.env.COOKIE_DOMAIN, // .example.com
      path: "/",
      transient: false,
      secure: process.env.NODE_ENV === "production",
      sameSite: "lax"
    }
  },

  // Transaction cookie configuration
  enableParallelTransactions: true,
  transactionCookie: {
    maxAge: 1800, // 30 minutes
    prefix: "auth_txn_",
    sameSite: "lax",
    secure: process.env.NODE_ENV === "production",
    path: "/"
  }
});

​
Best Practices

  • Always use secure: true in production to protect cookies from interception
  • Use sameSite: "lax" for most applications (good balance of security and usability)
  • Set appropriate domain only when sharing sessions across subdomains you control
  • Keep maxAge reasonable for transaction cookies (15-60 minutes)
  • Use parallel transactions unless you have specific reasons not to
  • Test cookie settings in development to ensure they work as expected
  • Monitor cookie size to stay within browser limits (4KB)

​
Security Considerations

  • Never set httpOnly: false - This is not allowed by the SDK for security reasons
  • Use secure: true in production - Prevents cookie theft over insecure connections
  • Be cautious with domain settings - Overly broad domains expose cookies to more subdomains
  • Use sameSite protection - Prevents CSRF attacks
  • Validate dynamic base URLs - Ensure Auth0 Allowed URLs are properly configured

​
Troubleshooting

​
Cookies not being set

If cookies aren’t being set:
  • Check that secure: true is only used with HTTPS
  • Verify sameSite: "none" is paired with secure: true
  • Ensure domain is valid for your hostname
  • Check browser console for cookie warnings

​
Cookies not sent with requests

If cookies aren’t sent:
  • Verify path includes the request path
  • Check domain matches the request hostname
  • Ensure sameSite settings allow the request type
  • Check for third-party cookie blocking in browser

​
Session not persisting

If sessions don’t persist:
  • Check if transient: true (cookies expire on browser close)
  • Verify cookie expiration settings
  • Ensure middleware is running on requests
  • Check for cookie size limits (4KB max)

​
Transaction cookies accumulating

If you see many transaction cookies:
  • Switch to single transaction mode: enableParallelTransactions: false
  • Reduce maxAge to clean up faster
  • Ensure authentication flows complete successfully
  • Check that callback route is processing correctly

Build docs developers (and LLMs) love

Get started for freeTalk to us