Set the authentication encryption key
Application initialization
Better Auth · Pipe
secret
secret configures the value Better Auth uses for encryption, signing, and hashing. It can be set explicitly or supplied through BETTER_AUTH_SECRET or AUTH_SECRET.
How it works
The secret option supplies the value Better Auth uses for encryption, signing, and hashing. If omitted, Better Auth checks BETTER_AUTH_SECRET and then AUTH_SECRET; production configuration must provide a secret rather than relying on the built-in fallback.
Syntax
betterAuth({ secret: "your-secret-key" })Parameters
| Name | Type | Description |
|---|---|---|
secret | string | A secret value used for encryption, signing, and hashing; it can be supplied as a configured string. |
Returns
A Better Auth configuration option; it does not return a value by itself.
Key points
- The option protects three core operations: encryption, signing, and hashing.
- When the option is not explicit, Better Auth resolves supported environment variables automatically.
BETTER_AUTH_SECRETis the first environment variable checked by the default lookup.AUTH_SECRETis the second environment variable checked by the default lookup.- The documentation recommends generating a value with the provided OpenSSL command rather than inventing a predictable string.
Common mistakes
- A production deployment fails if neither supported environment variable nor an explicit secret is configured.
- Without configuration, Better Auth has a default secret, so explicitly set a deployment-specific value instead of depending on that fallback.
Example: Configure a Better Auth secret
import { betterAuth } from "better-auth";
export const auth = betterAuth({
secret: process.env.BETTER_AUTH_SECRET,
});Configure the authentication instance with a secret supplied through the environment.
When to use it
Load the secret without hard-coding it
Environment-based deployment
Keep a legacy fallback while rotating keys
Secret migration
Interview questions
QWhat is the purpose of the Better Auth secret option?
The secret option is the key Better Auth uses for encryption, signing, and hashing. It can be supplied directly or through BETTER_AUTH_SECRET or AUTH_SECRET.
Follow-up: What happens if no value is configured in production? Better Auth throws an error rather than continuing with the default.
QWhich environment variables does Better Auth check?
Better Auth first looks for process.env.BETTER_AUTH_SECRET, then process.env.AUTH_SECRET. If neither exists, it uses its documented fallback value, although production should configure a real secret.
Follow-up: How should a secret be generated? Use a high-entropy value; the documentation provides openssl rand -base64 32.
QHow does secret relate to secret rotation?
The plural secrets option supports versioned secret rotation. During migration, the singular secret can remain as a fallback for decrypting legacy data within the same encryption purpose.
Follow-up: Does retaining the old singular secret preserve every old state artifact? No; the documentation specifically excludes pending OAuth or SAML state cookies and OAuth Proxy payloads when changing to purpose-specific keys.
Related
secretsBETTER_AUTH_SECRETAUTH_SECRETsecurityBETTER_AUTH_SECRETS