Configuration Reference

This page documents every option accepted by betterAuth(). For the full TypeScript source, see packages/better-auth/src/types/options.ts.

Quick example

auth.ts

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

string

The human-readable name of your application. Used in emails and the default error page.

appName: "My App"

string

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.

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.

string

default:"/api/auth"

The path prefix where Better Auth routes are mounted. Overridden when baseURL includes a path.

basePath: "/api/auth"

string

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.

# generate a strong secret
openssl rand -base64 32

secret: process.env.BETTER_AUTH_SECRET

Array<{ version: number; value: string }>

Versioned secrets for non-destructive secret rotation. The first entry is the active key for all new encryption; remaining entries are decryption-only.

secrets: [
  { version: 2, value: "new-secret-key" },
  { version: 1, value: "old-secret-key" },
]

Can also be set via the BETTER_AUTH_SECRETS environment variable:

.env

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.

string[] | ((request?: Request) => string[] | Promise<string[]>)

Origins allowed to make cross-origin requests. Accepts a static array, wildcard patterns, or an async function for dynamic resolution.Static:

trustedOrigins: ["http://localhost:3000", "https://example.com"]

Wildcard patterns:

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:

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.

BetterAuthPlugin[]

List of Better Auth plugins to load.

import { emailOTP } from "better-auth/plugins";

plugins: [
  emailOTP({
    sendVerificationOTP: async ({ email, otp, type }) => {
      // send OTP
    },
  }),
]

string[]

Auth paths that should return 404. Useful for disabling sign-up in closed-beta or invite-only apps.

disabledPaths: ["/sign-up/email"]

{ enabled: boolean }

default:"{ enabled: false }"

Controls anonymous usage telemetry sent to the Better Auth team.

telemetry: { enabled: false }

`database`

DatabaseConfiguration

Primary database configuration. Supports PostgreSQL, MySQL, and SQLite via the built-in Kysely adapter, or any ORM adapter (Prisma, Drizzle, MongoDB).

database: {
  dialect: "postgres",
  type: "postgres",
  casing: "camel",
}

Read the database docs for adapter-specific setup.

SecondaryStorageConfig

Optional fast key-value storage (Redis, Cloudflare KV, etc.) for sessions, verification tokens, and rate-limit counters.

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`

boolean

default:"false"

Enable email and password authentication.

Prevent new accounts from being created via email/password.

boolean

Block session creation until the user verifies their email.

number

default:"8"

Minimum accepted password length.

number

default:"128"

Maximum accepted password length.

Automatically create a session after a successful sign-up.

(opts: { user, url, token }) => Promise<void>

Function called to deliver the password-reset email.

sendResetPassword: async ({ user, url, token }) => {
  await mailer.send({ to: user.email, subject: "Reset password", html: url });
}

number

default:"3600"

Seconds until a reset-password token expires.

boolean

default:"false"

Revoke all other sessions when a user resets their password.

{ hash, verify }

Override the default scrypt password hashing with a custom implementation.

password: {
  hash: async (password) => bcrypt.hash(password, 10),
  verify: async ({ hash, password }) => bcrypt.compare(password, hash),
}

`emailVerification`

(opts: { user, url, token }) => Promise<void>

Function called to send verification emails.

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.

number

default:"3600"

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.

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`

string

default:"session"

Database table/model name for sessions.

number

default:"604800"

Session lifetime in seconds (default: 7 days).

number

default:"86400"

Extend the session expiry when the session age exceeds this threshold (seconds). Set to 0 to refresh on every request.

boolean

default:"false"

Disable automatic expiry extension regardless of updateAge.

Record<string, FieldConfig>

Extra fields to store on the session record.

boolean

default:"false"

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.

cookieCache: {
  enabled: true,
  maxAge: 300, // 5 minutes
}

session: {
  expiresIn: 604800,   // 7 days
  updateAge: 86400,    // refresh once per day
  cookieCache: {
    enabled: true,
    maxAge: 300,
  },
}

`user`

string

default:"user"

Database table/model name for users.

Record<string, string>

Map built-in field names to different database column names.

fields: { email: "emailAddress", name: "fullName" }

Record<string, FieldConfig>

Extra fields added to the user table. Set input: false for fields that should not be settable by the client (e.g. role).

additionalFields: {
  role: { type: "string", input: false },
}

ChangeEmailConfig

Configuration for the change-email flow.

enabled — allow authenticated users to change their email
sendChangeEmailConfirmation — function to deliver confirmation link

DeleteUserConfig

Configuration for account deletion.

enabled — allow users to delete their own account
sendDeleteAccountVerification — function to deliver confirmation link
beforeDelete / afterDelete — lifecycle callbacks

`account`

boolean

default:"false"

Encrypt access/refresh tokens before writing them to the database.

boolean

default:"true"

Allow users to link multiple OAuth providers to one account.

string[] | ((request?) => string[])

Providers whose verified email is trusted for automatic account linking.

trustedProviders: ["google", "github", "email-password"]

`rateLimit`

boolean

Defaults to true in production, false in development.

number

default:"10"

Time window in seconds.

number

default:"100"

Maximum requests per window across all routes.

Record<string, { window: number; max: number }>

Per-path overrides.

customRules: {
  "/sign-in/email": { window: 10, max: 5 },
}

'memory' | 'database' | 'secondary-storage'

default:"memory"

Where to persist rate-limit counters.

rateLimit: {
  enabled: true,
  window: 10,
  max: 100,
  customRules: {
    "/sign-in/email": { window: 10, max: 5 },
  },
}

`advanced`

boolean

default:"false"

Force the Secure flag on cookies regardless of protocol. Automatically true when baseURL uses https.

boolean

default:"false"

Disable all CSRF protection including origin header validation and Fetch Metadata checks.

Disabling CSRF checks exposes your application to CSRF attacks.

boolean

default:"false"

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.

{ enabled: boolean; domain: string; additionalCookies?: string[] }

Share session cookies across subdomains.

crossSubDomainCookies: {
  enabled: true,
  domain: "example.com",
}

Custom prefix for all cookie names.

string[]

Trusted headers to read the client IP from.

ipAddressHeaders: ["cf-connecting-ip"]

function | false | 'serial' | 'uuid'

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

(promise: Promise<unknown>) => void

Defer non-critical work to run after the response is sent. Pass waitUntil from your serverless platform.

// 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.

boolean

default:"false"

Treat routes with and without a trailing slash as equivalent.

`logger`

'debug' | 'info' | 'warn' | 'error'

default:"warn"

Minimum log level to output.

boolean

default:"false"

Suppress all log output.

(level, message, ...args) => void

Replace the built-in logger with a custom implementation.

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.

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.

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 for full details.

`onAPIError`

boolean

default:"false"

Re-throw API errors instead of returning an error response.

(error, ctx) => void

Custom error handler invoked on every API error.

string

default:"/api/auth/error"

Redirect target for errors that occur in browser flows.

ErrorPageTheme

Customize colors, sizes, and fonts of the built-in error page at /api/auth/error.

`verification`

boolean

default:"false"

Skip deleting expired verification records on read.

'plain' | 'hashed' | CustomHasher

How to store verification identifiers (OTP keys, magic-link tokens, etc.).

boolean

default:"false"

Write verification records to the primary database even when secondaryStorage is configured.

API Reference

Guides

Resources

Configuration Reference

Quick example

Top-level options

`database`

`emailAndPassword`

`emailVerification`

`socialProviders`

`session`

`user`

`account`

`rateLimit`

`advanced`

`logger`

`databaseHooks`

`hooks`

`onAPIError`

`verification`

​Quick example

​Top-level options

​database

​emailAndPassword

​emailVerification

​socialProviders

​session

​user

​account

​rateLimit

​advanced

​logger

​databaseHooks

​hooks

​onAPIError

​verification

Quick example

Top-level options

`database`

`emailAndPassword`

`emailVerification`

`socialProviders`

`session`

`user`

`account`

`rateLimit`

`advanced`

`logger`

`databaseHooks`

`hooks`

`onAPIError`

`verification`