Customize cookie names
An application must use a cookie name that matches an existing deployment or routing convention.
Auth.js · Pipe
cookies
Auth.js lets you override names and options for its cookies through the cookies configuration. Unspecified values retain Auth.js defaults, while session-cookie contents depend on the JWT or database session strategy.
How it works
Auth.js stores session state in cookies and lets you override selected cookie names and options through the main configuration. Unspecified properties continue using Auth.js defaults; cookie security behavior depends on the URL and the configured options.
Syntax
cookies?: Partial<CookiesOptions>;Parameters
| Name | Type | Description |
|---|---|---|
cookies | Partial<CookiesOptions> | Partial cookie configuration; entries can override cookie names and options, with omitted values using Auth.js defaults. |
Key points
- Set
cookiesin the Auth.js configuration to customize names or attributes for supported cookies. - Cookie overrides are granular: configure only the cookie entries that need different behavior.
- Properties omitted from an override inherit Auth.js’s defaults.
- Without a database adapter, the default session strategy stores an encrypted JWT in the cookie.
- Adding an adapter changes the default session strategy to database-backed sessions.
- Database sessions keep only the session token in the cookie; session data remains server-side.
- The secure-cookie setting can require HTTPS for every cookie Auth.js sets.
Common mistakes
- Custom cookie settings can opt out of Auth.js’s built-in dynamic policy, so development and production may need different configurations.
- Disabling secure-only cookies permits access from non-HTTPS URLs and is not recommended.
Example: Customize the session cookie
import NextAuth from "next-auth";
export const { handlers, auth } = NextAuth({
cookies: {
sessionToken: {
name: "app.session-token",
options: {
httpOnly: true,
sameSite: "lax",
path: "/",
secure: process.env.NODE_ENV === "production"
}
}
}
});Overrides the session cookie name while retaining explicit secure cookie attributes.
When to use it
Set cookie attributes
A security review requires explicit cookie attributes such as HTTPS-only access or a defined same-site policy.
Reason about database sessions
An adapter-backed application needs to understand what value is stored client-side.
Interview questions
QHow do you customize an Auth.js cookie?
The cookies option accepts a partial cookie configuration, allowing selected cookie names and options to be overridden. Any omitted options use Auth.js defaults.
Follow-up: What happens when only the cookie name is supplied? The remaining cookie settings are filled from the corresponding Auth.js defaults.
QWhat does the session cookie contain under each session strategy?
With a JWT strategy, Auth.js places an encrypted JWT in the session cookie by default. If an adapter is used, the default strategy changes to database sessions, where the cookie contains a session token instead.
Follow-up: How can JWT sessions still be selected with an adapter? Set session.strategy explicitly to "jwt".
QHow does Auth.js handle cookie security across environments?
The secure-cookie behavior restricts cookies to HTTPS URLs when enabled. Auth.js uses a less restrictive default for local http:// development URLs, but disabling the security behavior manually is not recommended.
Follow-up: Why might production and development need separate cookie policies? Custom cookie settings can bypass Auth.js’s dynamic policy, so the URL environment must be handled explicitly.
Related
CookieOptionCookiesOptionssession.strategysessionTokencallbackUrlcsrfTokenpkceCodeVerifierstate