Skip to main content
AuthKit Next.js uses HTTP-only cookies to store encrypted session data. This guide covers advanced cookie configuration and security considerations. AuthKit uses two types of cookies: The main session cookie stores encrypted session data including access and refresh tokens.
  • Name: wos-session (default, configurable via WORKOS_COOKIE_NAME)
  • Duration: 400 days (default, configurable via WORKOS_COOKIE_MAX_AGE)
  • Security: HttpOnly, Secure (on HTTPS), encrypted with WORKOS_COOKIE_PASSWORD
  • Size: ~2-4 KB depending on user data
When using eager auth, a temporary cookie provides synchronous token access.
  • Name: workos-access-token
  • Duration: 30 seconds
  • Purpose: Enable immediate client-side token access on page load
  • Auto-consumed: Deleted after first read

​
HttpOnly

Status: Always enabled Prevents JavaScript access to the cookie, protecting against XSS attacks. 
// From cookie.ts:84
return {
  path: '/',
  httpOnly: true,  // Always true
  secure,
  sameSite,
  maxAge,
  domain: WORKOS_COOKIE_DOMAIN || '',
};

​
Secure

Status: Automatically set based on protocol Ensures cookies are only sent over HTTPS connections. 
// From cookie.ts:44-57
let secure: boolean;
if (sameSite.toLowerCase() === 'none') {
  secure = true;  // Required for SameSite=None
} else if (urlString) {
  const url = new URL(urlString);
  secure = url.protocol === 'https:';
} else {
  secure = true;  // Production default
}
In local development with http://localhost, the Secure flag is automatically disabled to allow cookie storage.

​
SameSite

Controls when cookies are sent with cross-site requests.
Recommended for most applicationsCookies are sent with:
  • Same-site requests
  • Top-level navigation (e.g., clicking a link)
Not sent with:
  • Cross-site POST requests
  • Embedded iframes
WORKOS_COOKIE_SAMESITE='lax'

​
Maximum age

Configure how long the cookie remains valid: 
# Default: 400 days (Chrome's maximum)
WORKOS_COOKIE_MAX_AGE='34560000'

# 1 day
WORKOS_COOKIE_MAX_AGE='86400'

# 1 hour (short-lived sessions)
WORKOS_COOKIE_MAX_AGE='3600'
The cookie expiry is separate from token expiry. The access token typically expires after 15 minutes, but the cookie persists to enable automatic token refresh.

​
Token refresh cycle

The long cookie duration enables seamless token refresh without requiring users to re-authenticate.

​
Domain configuration

​
Single domain (default)

Cookies are scoped to the current domain only: 
# No configuration needed
# Cookie valid for: app.example.com only

​
Shared domains

Share sessions across multiple subdomains: 
WORKOS_COOKIE_DOMAIN='example.com'
This makes cookies valid for:
  • example.com
  • app.example.com
  • dashboard.example.com
  • Any other subdomain
All applications sharing the cookie domain must use the same WORKOS_COOKIE_PASSWORD to decrypt the session.

​
Multi-application sessions

Example setup for shared authentication across multiple apps:
1

Configure shared domain

Set the same cookie domain in all applications:
# App 1 (app.example.com)
WORKOS_COOKIE_DOMAIN='example.com'
WORKOS_COOKIE_PASSWORD='shared-secret-min-32-chars'

# App 2 (dashboard.example.com)
WORKOS_COOKIE_DOMAIN='example.com'
WORKOS_COOKIE_PASSWORD='shared-secret-min-32-chars'  # Must match!
2

Configure redirect URIs

Each app needs its own callback URL in WorkOS dashboard:
  • https://app.example.com/callback
  • https://dashboard.example.com/callback
3

Sign in from any app

Users authenticate once and the session is available across all configured domains.
Customize the cookie name to avoid conflicts: 
WORKOS_COOKIE_NAME='my-app-session'
Useful when:
  • Running multiple AuthKit instances on the same domain
  • Migrating from another authentication system
  • Testing different configurations simultaneously
Session cookies contain:
  • Access token (~1.5 KB)
  • Refresh token (~200 bytes)
  • User object (~1-2 KB depending on fields)
  • Impersonator data (if present)
Total size is typically 2-4 KB, well within browser limits (4 KB per cookie).
Cookies larger than 4 KB will be rejected by browsers. Avoid storing additional data in the session cookie.

​
Security best practices

Always deploy with HTTPS to ensure cookies have the Secure flag and cannot be intercepted.
Use lax or strict unless you specifically need cross-origin cookie access.

​
Troubleshooting

Possible causes:
  • Protocol mismatch (trying to set Secure cookies on HTTP)
  • Domain mismatch (cookie domain doesn’t match current domain)
  • Cookie size exceeds 4 KB
Solution: Check browser developer tools > Application > Cookies to see rejection reasons.
Issue: User authenticated on app.example.com but not on dashboard.example.comSolution:
  1. Set WORKOS_COOKIE_DOMAIN='example.com' in both apps
  2. Use the same WORKOS_COOKIE_PASSWORD in both apps
  3. Clear existing cookies and re-authenticate
Issue: Cookies rejected in embedded contexts (iframes)Solution:
  1. Ensure you’re using HTTPS (required for SameSite=None)
  2. Set WORKOS_COOKIE_SAMESITE='none'
  3. Verify the Secure flag is present in browser dev tools

Environment variables

Complete configuration reference

CDN deployments

Cache control and CDN considerations

Build docs developers (and LLMs) love

Get started for freeTalk to us