> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/better-auth/better-auth/llms.txt
> Use this file to discover all available pages before exploring further.
# Configuration Reference
> Complete reference for all betterAuth() configuration options.
This page documents every option accepted by `betterAuth()`. For the full TypeScript source, see [`packages/better-auth/src/types/options.ts`](https://github.com/better-auth/better-auth/blob/main/packages/better-auth/src/types/options.ts).
## Quick example
```ts title="auth.ts" theme={null}
import { betterAuth } from "better-auth";
export const auth = betterAuth({
appName: "My App",
baseURL: "https://example.com",
secret: process.env.BETTER_AUTH_SECRET,
database: { dialect: "postgres", type: "postgres" },
emailAndPassword: { enabled: true },
socialProviders: {
github: {
clientId: process.env.GITHUB_CLIENT_ID!,
clientSecret: process.env.GITHUB_CLIENT_SECRET!,
},
},
});
```
***
## Top-level options
The human-readable name of your application. Used in emails and the default
error page.
```ts theme={null}
appName: "My App"
```
Root URL where your application server is hosted. If a path component is
included it takes precedence over `basePath`.
Falls back to the `BETTER_AUTH_URL` environment variable, then to request
inference. Always set this explicitly in production.
```ts theme={null}
baseURL: "https://example.com"
```
Relying on request inference is not recommended. For security and stability,
always set `baseURL` explicitly or via the `BETTER_AUTH_URL` environment
variable.
The path prefix where Better Auth routes are mounted. Overridden when
`baseURL` includes a path.
```ts theme={null}
basePath: "/api/auth"
```
Secret used for encryption, signing, and hashing. In production Better Auth
throws if this is not set.
Reads from `BETTER_AUTH_SECRET` or `AUTH_SECRET` environment variables when
not provided explicitly.
```bash theme={null}
# generate a strong secret
openssl rand -base64 32
```
```ts theme={null}
secret: process.env.BETTER_AUTH_SECRET
```
Versioned secrets for non-destructive secret rotation. The first entry is the
**active** key for all new encryption; remaining entries are decryption-only.
```ts theme={null}
secrets: [
{ version: 2, value: "new-secret-key" },
{ version: 1, value: "old-secret-key" },
]
```
Can also be set via the `BETTER_AUTH_SECRETS` environment variable:
```txt title=".env" theme={null}
BETTER_AUTH_SECRETS=2:new-secret-base64,1:old-secret-base64
```
When `secrets` is configured, the singular `secret` is only used as a fallback
for decrypting legacy data. Both can coexist during migration.
Origins allowed to make cross-origin requests. Accepts a static array,
wildcard patterns, or an async function for dynamic resolution.
**Static:**
```ts theme={null}
trustedOrigins: ["http://localhost:3000", "https://example.com"]
```
**Wildcard patterns:**
```ts theme={null}
trustedOrigins: [
"https://*.example.com", // all HTTPS subdomains
"myapp://", // mobile deep-link scheme
"chrome-extension://ABC123", // browser extension
]
```
| Pattern | Description |
| ------- | ---------------------------------------------------- |
| `?` | Matches exactly one character (not `/`) |
| `*` | Matches zero or more characters that don't cross `/` |
| `**` | Matches zero or more characters including `/` |
**Dynamic:**
```ts theme={null}
trustedOrigins: async (request) => {
if (!request) return ["https://my-frontend.com"];
return ["https://dynamic-origin.com"];
}
```
The `request` parameter is `undefined` during initialization and when
calling `auth.api` directly. Always return default origins for the
`undefined` case.
List of Better Auth plugins to load.
```ts theme={null}
import { emailOTP } from "better-auth/plugins";
plugins: [
emailOTP({
sendVerificationOTP: async ({ email, otp, type }) => {
// send OTP
},
}),
]
```
Auth paths that should return 404. Useful for disabling sign-up in
closed-beta or invite-only apps.
```ts theme={null}
disabledPaths: ["/sign-up/email"]
```
Controls anonymous usage telemetry sent to the Better Auth team.
```ts theme={null}
telemetry: { enabled: false }
```
***
## `database`
Primary database configuration. Supports PostgreSQL, MySQL, and SQLite via
the built-in Kysely adapter, or any ORM adapter (Prisma, Drizzle, MongoDB).
```ts theme={null}
database: {
dialect: "postgres",
type: "postgres",
casing: "camel",
}
```
Read the [database docs](/concepts/database) for adapter-specific setup.
Optional fast key-value storage (Redis, Cloudflare KV, etc.) for sessions,
verification tokens, and rate-limit counters.
```ts theme={null}
secondaryStorage: {
get: async (key) => redis.get(key),
set: async (key, value, ttl) => redis.set(key, value, "EX", ttl),
delete: async (key) => redis.del(key),
}
```
***
## `emailAndPassword`
Enable email and password authentication.
Prevent new accounts from being created via email/password.
Block session creation until the user verifies their email.
Minimum accepted password length.
Maximum accepted password length.
Automatically create a session after a successful sign-up.
Function called to deliver the password-reset email.
```ts theme={null}
sendResetPassword: async ({ user, url, token }) => {
await mailer.send({ to: user.email, subject: "Reset password", html: url });
}
```
Seconds until a reset-password token expires.
Revoke all other sessions when a user resets their password.
Override the default `scrypt` password hashing with a custom implementation.
```ts theme={null}
password: {
hash: async (password) => bcrypt.hash(password, 10),
verify: async ({ hash, password }) => bcrypt.compare(password, hash),
}
```
***
## `emailVerification`
Function called to send verification emails.
```ts theme={null}
sendVerificationEmail: async ({ user, url, token }) => {
await mailer.send({ to: user.email, subject: "Verify email", html: url });
}
```
Send a verification email automatically after sign-up. When `undefined`,
follows the `requireEmailVerification` setting.
Automatically sign the user in after they verify their email.
Seconds until a verification token expires.
***
## `socialProviders`
Configure one or more OAuth / OIDC providers. Each key is a provider slug.
OAuth client ID issued by the provider.
OAuth client secret issued by the provider.
Custom callback URL. Defaults to
`{baseURL}/api/auth/callback/{provider}`.
Additional OAuth scopes to request beyond the provider defaults.
Transform the raw provider profile into Better Auth user fields.
Prevent new accounts from being created through this provider.
```ts theme={null}
socialProviders: {
google: {
clientId: process.env.GOOGLE_CLIENT_ID!,
clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
},
github: {
clientId: process.env.GITHUB_CLIENT_ID!,
clientSecret: process.env.GITHUB_CLIENT_SECRET!,
},
}
```
***
## `session`
Database table/model name for sessions.
Session lifetime in seconds (default: 7 days).
Extend the session expiry when the session age exceeds this threshold
(seconds). Set to `0` to refresh on every request.
Disable automatic expiry extension regardless of `updateAge`.
Extra fields to store on the session record.
Persist sessions in the primary database even when `secondaryStorage` is
configured.
Cache session data in a short-lived signed cookie to avoid a database
round-trip on every request.
```ts theme={null}
cookieCache: {
enabled: true,
maxAge: 300, // 5 minutes
}
```
```ts theme={null}
session: {
expiresIn: 604800, // 7 days
updateAge: 86400, // refresh once per day
cookieCache: {
enabled: true,
maxAge: 300,
},
}
```
***
## `user`
Database table/model name for users.
Map built-in field names to different database column names.
```ts theme={null}
fields: { email: "emailAddress", name: "fullName" }
```
Extra fields added to the user table. Set `input: false` for fields that
should not be settable by the client (e.g. `role`).
```ts theme={null}
additionalFields: {
role: { type: "string", input: false },
}
```
Configuration for the change-email flow.
* `enabled` — allow authenticated users to change their email
* `sendChangeEmailConfirmation` — function to deliver confirmation link
Configuration for account deletion.
* `enabled` — allow users to delete their own account
* `sendDeleteAccountVerification` — function to deliver confirmation link
* `beforeDelete` / `afterDelete` — lifecycle callbacks
***
## `account`
Encrypt access/refresh tokens before writing them to the database.
Allow users to link multiple OAuth providers to one account.
Providers whose verified email is trusted for automatic account linking.
```ts theme={null}
trustedProviders: ["google", "github", "email-password"]
```
***
## `rateLimit`
Defaults to `true` in production, `false` in development.
Time window in seconds.
Maximum requests per window across all routes.
Per-path overrides.
```ts theme={null}
customRules: {
"/sign-in/email": { window: 10, max: 5 },
}
```
Where to persist rate-limit counters.
```ts theme={null}
rateLimit: {
enabled: true,
window: 10,
max: 100,
customRules: {
"/sign-in/email": { window: 10, max: 5 },
},
}
```
***
## `advanced`
Force the `Secure` flag on cookies regardless of protocol. Automatically
`true` when `baseURL` uses `https`.
Disable all CSRF protection including origin header validation and Fetch
Metadata checks.
Disabling CSRF checks exposes your application to CSRF attacks.
Disable URL validation for `callbackURL`, `redirectTo`, and other redirect
targets. Also disables CSRF protection for backward compatibility.
Disabling origin checks opens your app to open-redirect attacks.
Share session cookies across subdomains.
```ts theme={null}
crossSubDomainCookies: {
enabled: true,
domain: "example.com",
}
```
Custom prefix for all cookie names.
Trusted headers to read the client IP from.
```ts theme={null}
ipAddressHeaders: ["cf-connecting-ip"]
```
Override the default nanoid-based ID generation.
* `false` — let the database generate IDs
* `"serial"` — use auto-increment
* `"uuid"` — use random UUID
* function — custom generator `(opts: { model, size? }) => string`
Defer non-critical work to run after the response is sent. Pass
`waitUntil` from your serverless platform.
```ts theme={null}
// Vercel
import { waitUntil } from "@vercel/functions";
backgroundTasks: { handler: waitUntil }
// Cloudflare Workers
backgroundTasks: { handler: (p) => ctx.waitUntil(p) }
```
Enabling background tasks introduces eventual consistency — the response
may return optimistic data before the database is updated.
Treat routes with and without a trailing slash as equivalent.
***
## `logger`
Minimum log level to output.
Suppress all log output.
Replace the built-in logger with a custom implementation.
```ts theme={null}
log: (level, message, ...args) => {
myLoggingService.log({ level, message, metadata: args });
}
```
***
## `databaseHooks`
Run code before or after core database operations. The `before` hook can
return modified data; the `after` hook is fire-and-forget.
```ts theme={null}
databaseHooks: {
user: {
create: {
before: async (user) => {
return { data: { ...user, role: "member" } };
},
after: async (user) => {
await analytics.track("user_created", { id: user.id });
},
},
},
session: { /* ... */ },
account: { /* ... */ },
verification: { /* ... */ },
}
```
***
## `hooks`
Request-level middleware that runs before or after every matched request.
```ts theme={null}
import { createAuthMiddleware } from "better-auth/api";
hooks: {
before: createAuthMiddleware(async (ctx) => {
console.log("→", ctx.path);
}),
after: createAuthMiddleware(async (ctx) => {
console.log("←", ctx.context.returned);
}),
}
```
See the [hooks documentation](/concepts/hooks) for full details.
***
## `onAPIError`
Re-throw API errors instead of returning an error response.
Custom error handler invoked on every API error.
Redirect target for errors that occur in browser flows.
Customize colors, sizes, and fonts of the built-in error page at
`/api/auth/error`.
***
## `verification`
Skip deleting expired verification records on read.
How to store verification identifiers (OTP keys, magic-link tokens, etc.).
Write verification records to the primary database even when
`secondaryStorage` is configured.