options/core

25 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

secondaryStorage example code

import { betterAuth } from "better-auth"; export const auth = betterAuth({ // ... other options secondaryStorage: { // Your implementation here }, })

appName option

The appName option sets the name of the application, which defaults to 'Better Auth'. It is used as a display name in contexts where the app needs to be identified, for example as the issuer name in TOTP entries for two-factor authentication with authenticator apps. It can be overridden per-plugin.

baseURL option - string form

The baseURL option sets the base URL for Better Auth as a static string for single-domain deployments. If a path is included in the baseURL string, it takes precedence over the default path. By default, Better Auth checks the BETTER_AUTH_URL environment variable, then AUTH_SECRET environment variable, then infers from the incoming request. Relying on request inference is not recommended for security and stability.

baseURL option - dynamic object form

The baseURL option can be an object for dynamic per-request resolution across multiple allowed hosts. It has three sub-options: allowedHosts (list of accepted host patterns supporting exact matches like 'myapp.com', wildcards like '*.vercel.app' and 'preview-*.myapp.com', and port wildcards like 'localhost:*'; automatically added to trustedOrigins with localhost entries getting both http and https), protocol (string: 'http', 'https', or 'auto' for URL construction; 'auto' derives from x-forwarded-proto then request URL then defaults to HTTPS; affects cookie Secure flag), and fallback (URL to use when incoming host does not match; unknown hosts throw without it; its origin is added to trustedOrigins).

basePath option

The basePath option sets the base path for Better Auth routes. Default is '/api/auth'. It is overridden if there is a path component within baseURL.

secret option

The secret option is the secret used for encryption, signing, and hashing. By default, Better Auth checks for environment variables BETTER_AUTH_SECRET, then AUTH_SECRET. If neither is set, it defaults to 'better-auth-secret-12345678901234567890'. In production, if not set, it throws an error. A good secret can be generated with: openssl rand -base64 32

secrets option - versioned secret rotation

The secrets option enables versioned secrets for non-destructive secret rotation. Encrypted data uses an envelope format embedding the key version, allowing secret rotation without invalidating existing data. Format: array of objects with version (integer) and value (string) properties. The first entry is the current key for all new encryption. Remaining entries are decryption-only for previous rotations. Gaps are allowed. Can be set via BETTER_AUTH_SECRETS environment variable as 'version:base64,version:base64'. When secrets is set, secret (singular) is used only as fallback for decrypting legacy data predating the envelope format.

trustedOrigins option - static array form

The trustedOrigins option accepts a static array of origin strings. By default, Better Auth trusts the base URL of the app (baseURL). Additional trusted origins can be specified with values as an array of origin strings.

trustedOrigins option - dynamic function form

The trustedOrigins option can be a function that returns origins dynamically. The function receives a request parameter that is undefined during initialization and when calling auth.api directly. It must handle the undefined case by returning default trusted origins.

trustedOrigins wildcard patterns

The trustedOrigins option supports wildcard patterns. Pattern syntax: '?' matches exactly one character except '/'; '*' matches zero or more characters not crossing '/'; '**' matches zero or more characters including '/'. Examples: 'http://*.example.com' matches subdomains of example.com but not https or the domain itself; 'https://**.example.com' matches subdomains at any depth; 'https://example.com' matches only that exact origin. For http/https URLs, patterns match the full origin (paths and query strings ignored). For custom schemes like 'exp://' or 'myapp://', patterns match against the full URL including paths when wildcards exist, or use prefix matching when no wildcards exist. The separator is forward slash '/'.

database option

The database option configures database for Better Auth. It includes: dialect (database type), type (database type), casing (field name casing). Better Auth supports PostgreSQL, MySQL, and SQLite.

secondaryStorage option

The secondaryStorage option configures secondary storage used to store session data, verification records, and rate limit data.

database example code

import { betterAuth } from "better-auth"; export const auth = betterAuth({ database: { dialect: "postgres", type: "postgres", casing: "camel" }, })

disabledPaths option

The disabledPaths option accepts an array of auth paths to disable. Paths can be specified as strings like '/sign-up/email' or '/sign-in/email'.

telemetry option

The telemetry option has an enabled boolean field to enable or disable Better Auth's telemetry collection. Default is false.

appName example code

import { betterAuth } from "better-auth"; export const auth = betterAuth({ appName: "My App", })

baseURL example code - static string

import { betterAuth } from "better-auth"; export const auth = betterAuth({ baseURL: "https://example.com", })

baseURL example code - dynamic object

import { betterAuth } from "better-auth"; export const auth = betterAuth({ baseURL: { allowedHosts: [ "myapp.com", "www.myapp.com", "*.vercel.app", ], protocol: "https", fallback: "https://myapp.com", }, })

basePath example code

import { betterAuth } from "better-auth"; export const auth = betterAuth({ basePath: "/api/auth", })

secrets example code

import { betterAuth } from "better-auth"; export const auth = betterAuth({ secrets: [ { version: 2, value: "new-secret-key" }, { version: 1, value: "old-secret-key" }, ], })

trustedOrigins example code - static array

import { betterAuth } from "better-auth"; export const auth = betterAuth({ trustedOrigins: ["http://localhost:3000", "https://example.com"], })

trustedOrigins example code - dynamic function

export const auth = betterAuth({ trustedOrigins: async (request) => { // request is undefined during initialization and auth.api calls if (!request) { return ["https://my-frontend.com"]; } // Dynamic logic based on the request return ["https://dynamic-origin.com"]; } })

trustedOrigins example code - wildcard patterns

export const auth = betterAuth({ trustedOrigins: [ "https://*.example.com", // trust all HTTPS subdomains of example.com "http://*.dev.example.com" // trust all HTTP subdomains of dev.example.com ] })

disabledPaths example code

import { betterAuth } from "better-auth"; export const auth = betterAuth({ disabledPaths: ["/sign-up/email", "/sign-in/email"], })

telemetry example code

import { betterAuth } from "better-auth"; export const auth = betterAuth({ telemetry: { enabled: false, } })

Give your agent this brain