Skip to main content

​
Prerequisites

Before installing AuthKit Next.js, make sure you have:
  • A Next.js 13.5.9+ application using the App Router
  • A WorkOS account (sign up for free)
  • Node.js 18 or later

​
Install the package

Install AuthKit Next.js using your preferred package manager: 
pnpm add @workos-inc/authkit-nextjs

​
Environment variables

Create or update your .env.local file with the following required variables:
.env.local
WORKOS_CLIENT_ID="client_..."
WORKOS_API_KEY="sk_test_..."
WORKOS_COOKIE_PASSWORD="<your-password>"
NEXT_PUBLIC_WORKOS_REDIRECT_URI="http://localhost:3000/callback"

​
Get your WorkOS credentials

1

Find your Client ID

Navigate to the WorkOS Dashboard and copy your Client ID from the API Keys section.
2

Get your API Key

In the same section, copy your API Key. Use sk_test_... for development and sk_live_... for production.
3

Generate a cookie password

The cookie password must be at least 32 characters. Generate a secure password using one of these methods:
# Use the 1Password generator
# https://1password.com/password-generator/
4

Configure your redirect URI

In the WorkOS Dashboard, go to Configuration → Redirects and add your callback URL (e.g., http://localhost:3000/callback for development).
Never commit your .env.local file to version control. Add it to your .gitignore file to keep your credentials secure.

​
Optional configuration

Customize AuthKit behavior with these optional environment variables:
VariableDefaultDescription
WORKOS_COOKIE_MAX_AGE34560000 (400 days)Session cookie lifetime in seconds
WORKOS_COOKIE_DOMAINNoneCookie domain (leave empty for current domain only)
WORKOS_COOKIE_NAMEwos-sessionName of the session cookie
WORKOS_COOKIE_SAMESITElaxSameSite attribute: lax, strict, or none
WORKOS_API_HOSTNAMEapi.workos.comWorkOS API hostname
WORKOS_API_HTTPStrueUse HTTPS for API calls
WORKOS_API_PORTNoneCustom port for API calls
.env.local
# Short-lived sessions (10 minutes)
WORKOS_COOKIE_MAX_AGE="600"

# Share sessions across subdomains
WORKOS_COOKIE_DOMAIN="example.com"

# Custom cookie name
WORKOS_COOKIE_NAME="my-auth-cookie"
Use WORKOS_COOKIE_DOMAIN to share WorkOS sessions between apps on different subdomains. All apps must use the same WORKOS_COOKIE_PASSWORD.
Setting WORKOS_COOKIE_SAMESITE="none" allows cookies in cross-origin contexts (like iframes) but reduces CSRF protection. Only use this if your application architecture requires it. This setting forces cookies to be secure (HTTPS only).

​
Logout URI configuration

To use the signOut() method, set a default Logout URI in your WorkOS dashboard:
1

Open dashboard settings

Go to the WorkOS Dashboard and navigate to Configuration → Redirects
2

Set logout URI

Add your logout redirect URL (e.g., http://localhost:3000 for development)
You can override this on a per-call basis: 
await signOut({ returnTo: 'https://your-app.com/goodbye' });

​
TypeScript configuration

AuthKit Next.js includes TypeScript definitions out of the box. No additional configuration is needed. If you’re using strict mode, you may want to enable these options in tsconfig.json:
tsconfig.json
{
  "compilerOptions": {
    "strict": true,
    "strictNullChecks": true
  }
}

​
Verify installation

Confirm the package is installed correctly: 
npm list @workos-inc/authkit-nextjs
You should see the package version in the output: 
@workos-inc/[email protected]

​
Next steps

Quickstart guide

Set up authentication in your Next.js app in under 5 minutes

Build docs developers (and LLMs) love

Get started for freeTalk to us