Single-secret authentication configuration
A standard deployment needs one stable value for protecting authentication state.
Auth.js · Pipe
secret
secret is the Auth.js configuration value used to hash tokens, sign cookies, and generate cryptographic keys. Provide a random string or an ordered array to support secret rotation.
How it works
Auth.js uses the secret to hash tokens, sign cookies, and derive cryptographic keys. You can supply one secret or an ordered array: the first secret able to decrypt an existing JWT is selected, while the first array entry protects newly created sessions.
Syntax
secret?: string | string[]Parameters
| Name | Type | Description |
|---|---|---|
secret | string | string[] | A random string, or an array of secrets used for token hashing, cookie signing, cryptographic keys, and JWT decryption. |
Key points
- The
secretconfiguration accepts either one string or an array of strings. - Auth.js uses the value for token hashing, cookie signing, and cryptographic-key generation.
- JWT encryption is enabled by default when Auth.js obtains the secret from
AUTH_SECRET. - The deployment-level secret protects cookies and tokens during authentication.
- Generate a suitable secret with the Auth.js CLI rather than inventing a predictable value.
- Among Auth.js environment variables,
AUTH_SECRETis the only one documented as strictly required.
Common mistakes
- When rotating secrets, place the newest value first so new sessions use it; older values can remain available for decrypting existing JWTs.
Example: Configure an Auth.js secret
import NextAuth from "next-auth"
export const { handlers, auth } = NextAuth({
providers: [],
secret: process.env.AUTH_SECRET,
})Set AUTH_SECRET in the environment, then pass it explicitly to the Auth.js configuration.
When to use it
Secret rotation
A team must replace a compromised or aging secret without invalidating every existing session at once.
Environment-based JWT protection
A deployment wants JWT encryption enabled through conventional environment configuration.
Interview questions
QWhat does the Auth.js secret protect?
The secret is used to hash tokens, sign cookies, and generate cryptographic keys. Auth.js also uses it for JWT encryption by default.
Follow-up: How can secrets be rotated without immediately invalidating sessions? Supply an array with the newest secret first; Auth.js tries the entries for decryption and uses the first entry for new sessions.
QWhat values can the secret option accept?
The configuration type is string | string[]. A single string is sufficient for normal operation, while an array supports key rotation.
Follow-up: What ordering is required during rotation? Put the newer secret at index zero so newly issued sessions use it.
QHow should a production secret be generated and supplied?
The AUTH_SECRET environment variable is the conventional deployment setting, and the CLI can generate a random value with npx auth secret. The deployment documentation recommends a cryptographically secure random string of at least 32 characters.
Follow-up: Why prefer environment configuration? It keeps the secret outside source code and allows deployment-specific values.
Related
AUTH_SECRETAuthConfigJWTMissingSecretnpx auth secret