options & configuration

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

appName option

The appName option sets the name of your application. It defaults to 'Better Auth'. It is used as a display name in contexts where your app needs to be identified, such as when users set up two-factor authentication with an authenticator app (like Google Authenticator), where appName appears as the issuer name in the TOTP entry. It can be overridden per-plugin, such as the 2FA plugin's issuer option.

baseURL option configuration

The baseURL option sets the base URL for Better Auth, typically the root URL where your application server is hosted. It can be configured as a static string for single-domain deployments or an object for dynamic per-request resolution across multiple allowed hosts. If you include a path in the baseURL string, it takes precedence over the default path. If not explicitly set, Better Auth checks for the BETTER_AUTH_URL environment variable, then falls back to inferring from the incoming request. Relying on request inference is not recommended for security and stability.

Dynamic Base URL object configuration

When using a dynamic baseURL, the object supports: allowedHosts (list of accepted host patterns supporting exact matches, wildcards like *.vercel.app, and port wildcards like localhost:*; automatically added to trustedOrigins), protocol (http, https, or auto for URL construction; auto derives from x-forwarded-proto then request URL then defaults to HTTPS), and fallback (URL to use when the incoming host does not match; its origin is added to trustedOrigins).

basePath option

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

trustedOrigins option with static array

The trustedOrigins option specifies additional trusted origins beyond the base URL. By default, Better Auth trusts the base URL. You can provide a static array of origins like ['http://localhost:3000', 'https://example.com'].

trustedOrigins option with dynamic function

The trustedOrigins option can accept a function that returns origins dynamically. The function receives a request parameter which is undefined during initialization and when calling auth.api directly, so you must handle this case by returning default trusted origins.

trustedOrigins wildcard pattern syntax

Wildcard patterns in trustedOrigins support three pattern types: ? matches exactly one character except /, * matches zero or more characters that don't cross /, and ** matches zero or more characters including /. For http:// and https:// URLs, patterns match the full origin and ignore paths and query strings. For custom schemes like exp:// or myapp://, patterns match against the full URL including paths when wildcards are present, or use prefix matching when no wildcards exist. The separator is / (forward slash).

secret option

The secret option sets the secret used for encryption, signing, and hashing. By default, Better Auth looks for BETTER_AUTH_SECRET or AUTH_SECRET environment variables. If neither is set, it defaults to 'better-auth-secret-12345678901234567890'. In production, if not set, it throws an error. You can generate a good secret using: openssl rand -base64 32

secrets option for non-destructive secret rotation

The secrets option enables versioned secrets for non-destructive secret rotation. When set, encrypted data uses an envelope format that embeds the key version, allowing you to rotate secrets without invalidating existing data. It accepts an array with version and value properties. The first entry is the current key used for all new encryption. Remaining entries are decryption-only (previous rotations). Versions are integers with gaps allowed. You can also set this via the BETTER_AUTH_SECRETS environment variable in the format 'version:secret-base64,version:secret-base64'. When secrets is set, secret (singular) is only used as a fallback for decrypting legacy data.

user option configuration

The user option configures user settings with properties: modelName (model name for user; default: 'user'), fields (map fields to different column names), additionalFields (additional fields for user table), changeEmail (configuration for changing email including enabled, sendChangeEmailConfirmation function, and updateEmailWithoutVerification), and deleteUser (configuration for user deletion including enabled, sendDeleteAccountVerification function, beforeDelete, and afterDelete callbacks).

session option configuration

The session option configures session settings with properties: modelName (model name; default: 'sessions'), fields (map fields to column names), expiresIn (expiration time in seconds; default: 604800 - 7 days), updateAge (how often session refreshes in seconds; default: 86400 - 1 day), disableSessionRefresh (disable session updates regardless of updateAge; default: false), additionalFields (additional fields for session table), storeSessionInDatabase (store session in database when secondary storage provided; default: false), preserveSessionInDatabase (preserve session records when deleted from secondary storage; default: false), and cookieCache (enable caching session in cookie with enabled and maxAge properties).

account option configuration

The account option configures account settings with properties: modelName (model name), fields (map fields to column names), encryptOAuthTokens (encrypt OAuth tokens before storing; default: false), updateAccountOnSignIn (update account data on sign in with latest provider data), storeStateStrategy (where to store OAuth state: 'cookie' or 'database'; defaults to 'database' when database/secondaryStorage configured, 'cookie' when neither), storeAccountCookie (store provider account data after OAuth in encrypted cookie; default: false, automatically true if no database), and accountLinking (configuration for account linking).

account storeStateStrategy option

The account.storeStateStrategy option controls where OAuth state data is stored during authentication. 'cookie' stores state payload in encrypted cookie keeping OAuth flow stateless avoiding database writes. 'database' stores state payload in verification storage/table, sets signed state cookie, and validates on OAuth callback. Defaults to 'database' when database or secondaryStorage is configured, 'cookie' only when neither is set. With secondaryStorage, OAuth state is stored there automatically.

account storeAccountCookie option

The account.storeAccountCookie option stores provider account data after OAuth flow in encrypted cookie, useful for database-less flows where OAuth token material (access tokens, refresh tokens, ID tokens, scopes, token expiry) must be available without account table. Default: false, automatically set to true if no database. Account cookie has five-minute max age and refreshes when Better Auth writes updated provider account data like after getAccessToken or /refresh-token. When this happens in server-side code, forward returned Set-Cookie header to browser. Better Auth chunks oversized account cookies but browsers and proxies can enforce limits; prefer database-backed storage for large JWTs or production flows. When enabled, read decrypted account cookie using getAccountCookie from 'better-auth/cookies'.

accountLinking configuration

The accountLinking configuration has properties: enabled (enable account linking; default: true), disableImplicitLinking (disable automatic account linking on OAuth sign-in; when true, same-email OAuth sign-in for existing user rejected with account_not_linked; new users can sign up via OAuth and authenticated users can link explicitly; default: false), trustedProviders (list of trusted providers, can be static array or async function for dynamic resolution), allowDifferentEmails (allow linking accounts with different emails), allowUnlinkingAll (allow users to unlink all accounts), and updateUserInfoOnLink (when linking, copy provider profile including name, image, and mapProfileToUser fields onto local user; local email and emailVerified never changed; default: false).

verification option configuration

The verification option configures verification settings with properties: modelName (model name for verification table), fields (map fields to column names), disableCleanup (disable cleaning up expired values when verification value fetched), storeIdentifier (how to store verification identifiers like tokens and OTP keys; supports 'plain', 'hashed', or custom hasher; can use {default, overrides} for different strategies per identifier prefix), and storeInDatabase (store verification records in database even when secondaryStorage configured; default: false).

onAPIError customizeDefaultErrorPage size

The customizeDefaultErrorPage.size object allows customizing error page sizing with properties: radiusSm (small border radius), radiusMd (medium border radius), radiusLg (large border radius), textSm (small text size), text2xl (2xl text size), text4xl (4xl text size), and text6xl (6xl text size).

advanced.ipAddress option

The advanced.ipAddress option configures IP address tracking with properties: ipAddressHeaders (trusted header names to read client IP addresses from), disableIpTracking (disable IP address tracking), and trustedProxies (reverse-proxy IPs or CIDR ranges; forwarded chain walked right to left, trusted hops skipped, first untrusted address used as client IP).

advanced.useSecureCookies option

The advanced.useSecureCookies option forces the Secure cookie attribute in all environments. By default, cookies are secure only in production environments. Set to true to force secure cookies everywhere.

advanced.disableCSRFCheck option

The advanced.disableCSRFCheck option disables all CSRF protection including origin header validation and Fetch Metadata checks. This is a security risk and should not be used in production.

advanced.disableOriginCheck option

The advanced.disableOriginCheck option disables URL validation for callbackURL, redirectTo, and other redirect URLs. This is a security risk and should not be used in production.

advanced.crossSubDomainCookies option

The advanced.crossSubDomainCookies option configures cookies to be shared across subdomains with properties: enabled (enable cross-subdomain cookies), additionalCookies (list of additional cookies to share), and domain (explicit domain for cookies; if not set and baseURL uses dynamic configuration, domain derives from resolved request host).

advanced.cookies option

The advanced.cookies option customizes individual cookie names and attributes. For each cookie name like session_token, you can set name (custom cookie name) and attributes (like httpOnly and secure).

advanced.defaultCookieAttributes option

The advanced.defaultCookieAttributes option sets default attributes for all cookies, such as httpOnly and secure.

advanced.cookiePrefix option

The advanced.cookiePrefix option sets a prefix for all cookies.

advanced.backgroundTasks option

The advanced.backgroundTasks option configures background task handling for deferred operations. Background tasks allow non-critical operations like cleanup, analytics, timing-attack mitigation, or rate limit counter updates to run after the response is sent, improving response times on serverless platforms. The handler property accepts a function like waitUntil from @vercel/functions on Vercel or cloudflare:workers on Cloudflare Workers. Enabling this introduces eventual consistency where response returns optimistic data before database is updated; only enable if application tolerates this trade-off.

advanced.skipTrailingSlashes option

The advanced.skipTrailingSlashes option skips trailing slash validation in route matching. Default: false.

logger option configuration

The logger option configures Better Auth logging with properties: disabled (disable all logging; default: false), disableColors (disable colors in default logger; default: determined by terminal color support), level (minimum log level: 'debug', 'info', 'warn', 'error'; default: 'warn'), and log (custom logging function receiving level, message, and args).

databaseHooks option configuration

The databaseHooks option configures database lifecycle hooks for core operations on user, session, account, and verification entities. Each entity can have create and update hooks with before and after callbacks that modify data before operation or perform actions after operation.

onAPIError option configuration

The onAPIError option configures API error handling with properties: throw (throw error on API error; default: false), onError (custom error handler receiving error and ctx), errorURL (URL to redirect on error; default: '/api/auth/error'), and customizeDefaultErrorPage (configure default error page colors, sizes, fonts, and disable options).

onAPIError customizeDefaultErrorPage colors

The customizeDefaultErrorPage.colors object allows customizing error page colors with properties: background, foreground, primary, primaryForeground, mutedForeground, border, destructive, titleBorder, titleColor, gridColor, cardBackground, and cornerBorder.

onAPIError customizeDefaultErrorPage font

The customizeDefaultErrorPage.font object allows customizing error page fonts with properties: defaultFamily (default font family) and monoFamily (monospace font family).

onAPIError customizeDefaultErrorPage disable options

The customizeDefaultErrorPage object supports boolean options: disableTitleBorder (disable border around title; default: false), disableCornerDecorations (disable corner decorations; default: false), and disableBackgroundGrid (disable background grid pattern; default: false).

hooks option configuration

The hooks option configures request lifecycle hooks with before and after properties, each accepting middleware created with createAuthMiddleware that can execute code before or after processing requests.

disabledPaths option

The disabledPaths option disables specific auth paths by accepting an array of path strings like ['/sign-up/email', '/sign-in/email'].

telemetry option

The telemetry option enables or disables Better Auth's telemetry collection with an enabled property. Default: false.

Give your agent this brain