core options

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

database option

The database option configures the database for Better Auth. It supports various configurations including PostgreSQL, MySQL, and SQLite. Example configuration includes dialect and type properties set to "postgres" or other supported databases, and casing options like "camel".

appName option

The appName option sets the name of your application, defaulting 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, where appName appears as the issuer name in the TOTP entry. This can be overridden per-plugin.

baseURL option

baseURL specifies 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 a path is included in the baseURL string, it takes precedence over the default path. If not explicitly set, the system checks for the BETTER_AUTH_URL environment variable; if that is also not set, it will be inferred from the incoming request. For security and stability, relying on request inference is not recommended.

baseURL dynamic object configuration

When using the dynamic baseURL object form, configure: allowedHosts (list of accepted host patterns supporting exact matches like "myapp.com", wildcards like "*.vercel.app", and port wildcards like "localhost:*", automatically added to trustedOrigins); protocol ("http", "https", or "auto" for URL construction, where "auto" uses x-forwarded-proto when advanced.trustedProxyHeaders is true, then the request URL, then HTTP for local loopback hosts, and otherwise HTTPS); fallback (URL to use when no request host is available or the incoming host does not match). When crossSubDomainCookies is enabled, the cookie domain is derived from the resolved request host unless explicitly set via domain.

basePath option

basePath specifies the base path for Better Auth, typically the path where the Better Auth routes are mounted. Default is "/api/auth". It will be overridden if there is a path component within baseURL.

trustedOrigins option

trustedOrigins specifies additional trusted origins beyond the base URL of your app. Values can be a static array of origins, a function that returns origins dynamically based on the request, or wildcard patterns to match multiple domains. The request parameter in the dynamic function is undefined during initialization and when calling auth.api directly.

trustedOrigins wildcard patterns

trustedOrigins supports wildcard patterns: ? matches exactly one character except /; * matches zero or more characters that don't cross /; ** matches zero or more characters including /. For http:// and https:// URLs, patterns match the full origin and paths/query strings are ignored. For custom schemes like exp:// or myapp://, patterns match against the full URL including paths, with a non-wildcard pattern matching by scheme and authority (host-less entries like myapp:// trust every host of that scheme, while host-bearing entries like myapp://callback must match that host exactly). The separator is / (forward slash).

secret option

The secret option specifies the secret used for encryption, signing, and hashing. By default, Better Auth looks for BETTER_AUTH_SECRET or AUTH_SECRET environment variables. If none are set, it defaults to "better-auth-secret-12345678901234567890". In production, if not set, it will throw an error. A good secret can be generated using: openssl rand -base64 32

secrets option for key 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 secret rotation without invalidating existing data. Configure as an array of objects with version and value properties. The first entry is the current key used for all new encryption; remaining entries are decryption-only for previous rotations. Versions are integers and gaps are allowed. Set via BETTER_AUTH_SECRETS environment variable as: 2:new-secret-base64,1:old-secret-base64. When secrets is set, secret (singular) is only used as a fallback for decrypting legacy data that predates the envelope format.

secondaryStorage option

The secondaryStorage option configures secondary storage used to store session data, verification records, and rate limit data. It is separate from the primary database configuration and allows for flexible storage strategies.

emailVerification configuration

emailVerification configuration options: sendVerificationEmail (function to send verification email to user); sendOnSignUp (send verification email automatically after sign up, true always sends, false never sends, undefined follows requireEmailVerification behavior, default: undefined); sendOnSignIn (send verification email on sign in when user's email is not verified, default: false); autoSignInAfterVerification (auto sign in user after email verification); expiresIn (number of seconds the verification token is valid for, default: 3600).

emailAndPassword configuration fields

emailAndPassword configuration includes: enabled (enable email and password authentication, default: false); disableSignUp (disable email and password sign up, default: false); requireEmailVerification (require email verification before session creation); minPasswordLength (minimum password length, default: 8); maxPasswordLength (maximum password length, default: 128); autoSignIn (automatically sign in user after sign up); sendResetPassword (function to send reset password email); onPasswordReset (callback when password is changed); revokeSessionsOnPasswordReset (revoke all other sessions when resetting password, default: false); resetPasswordTokenExpiresIn (seconds the reset password token is valid, default: 3600); onExistingUserSignUp (callback when signup with already-registered email, only called when requireEmailVerification is true or autoSignIn is false); customSyntheticUser (function to build custom synthetic user for email enumeration protection); password (custom password hashing and verification functions).

socialProviders configuration

socialProviders configuration for OAuth: clientId (OAuth client ID from the provider); clientSecret (OAuth client secret); clientKey (client key used by some providers like TikTok instead of clientId, optional); redirectURI (custom redirect URI for OAuth callback, optional); scope (additional OAuth scopes to request, optional); mapProfileToUser (custom function to map provider profile to user, optional); disableSignUp (disable sign up for new users, optional); disableImplicitSignUp (disable implicit sign up for new users, optional); overrideUserInfoOnSignIn (override user info with provider user info on sign in, optional); requireEmailVerification (require provider email verification before session creation, optional); prompt (authorization code request prompt: "select_account", "consent", "login", "none", "select_account consent", optional); responseMode ("query" or "form_post", optional); getUserInfo (custom function to get user info, optional); refreshAccessToken (custom function to refresh token, optional); verifyIdToken (custom function to verify ID token receiving (token, nonce?, ctx?), optional); disableIdTokenSignIn (disable sign in with ID token from client, optional); disableDefaultScope (disable provider's default scopes, optional); authorizationEndpoint (custom authorization endpoint URL, optional).

user configuration options

user configuration includes: modelName (model name for the user, default: "user"); fields (map fields to different column names); additionalFields (additional fields for the user table); changeEmail (configuration for changing email with enabled, sendChangeEmailConfirmation function, and updateEmailWithoutVerification options); deleteUser (configuration for user deletion with enabled, sendDeleteAccountVerification function, beforeDelete and afterDelete callbacks).

session configuration options

session configuration includes: modelName (model name for the session, default: "session"); fields (map fields to different column names); expiresIn (expiration time for session token in seconds, default: 604800 - 7 days); updateAge (how often session should be refreshed in seconds, default: 86400 - 1 day); disableSessionRefresh (disable session refresh, default: false); additionalFields (additional fields for session table); storeSessionInDatabase (store session in database when secondary storage is provided, default: false); preserveSessionInDatabase (preserve session records in database when deleted from secondary storage, default: false); cookieCache (enable caching session in cookie with enabled, maxAge, and strategy properties).

account configuration options

account configuration includes: modelName (model name for the account); fields (map fields to different column names); encryptOAuthTokens (encrypt OAuth tokens before storing in database, default: false); updateAccountOnSignIn (if enabled, update user account data on sign in with latest provider data); storeStateStrategy ("cookie" or "database", defaults to "database" when database or secondaryStorage configured, "cookie" only when neither is set); storeAccountCookie (store provider account data in encrypted cookie after OAuth flow, useful for database-less flows, default: false, automatically true if no database provided); accountLinking configuration.

storeStateStrategy OAuth configuration

storeStateStrategy controls where OAuth state data is stored during authentication flow: "cookie" stores the state payload in an encrypted cookie for stateless operation avoiding database write during flow start; "database" stores state payload in verification storage/table, sets a signed state cookie when starting flow, and validates stored state against signed cookie on OAuth callback. Defaults to "database" when database or secondaryStorage configured, and to "cookie" only when neither is set. With secondaryStorage, OAuth state is stored there automatically.

storeAccountCookie OAuth configuration

storeAccountCookie stores provider account data after OAuth flow in an encrypted cookie, useful for database-less flows. Default: false, automatically set to true if no database provided. The account cookie has a five-minute max age and is refreshed when Better Auth writes updated provider account data. When this happens in server-side code, forward the returned Set-Cookie header to browser for refreshed account cookie retention. Pass useAccountCookie: true to getAccessToken, refreshToken, or accountInfo when the signed cookie should select the account. These APIs require an explicit accountId or useAccountCookie: true. Better Auth chunks oversized account cookies but browsers and proxies can still enforce limits; prefer database-backed account storage for large JWTs or production flows. When enabled, read decrypted account cookie in hooks or middleware using getAccountCookie from better-auth/cookies.

accountLinking configuration

accountLinking configuration includes: enabled (enable account linking, default: true); disableImplicitLinking (disable automatic linking on OAuth sign-in, when true same-email OAuth sign-in for existing user rejected with account_not_linked instead of implicit linking even for verified emails or trustedProviders, default: false); trustedProviders (list of trusted providers, can be static array or async function returning providers based on request); allowDifferentEmails (allow linking accounts with different email addresses); allowUnlinkingAll (allow users to unlink all accounts); updateUserInfoOnLink (when linking, copy provider's profile name, image, and mapProfileToUser fields onto local user, local email and emailVerified never changed, default: false).

verification configuration options

verification configuration includes: modelName (model name for verification table); fields (map fields to different column names); disableCleanup (disable cleaning up expired values when verification value is fetched); storeIdentifier (how to store verification identifiers like tokens and OTP keys, supports "plain", "hashed", or custom hasher, can use { default, overrides } to apply different strategies per identifier prefix); storeInDatabase (store verification records in database even when secondaryStorage configured, default: false). If secondaryStorage configured, verification records stored there by default for flows using Better Auth's shared verification layer including OTP and magic-link flows.

rateLimit configuration options

rateLimit configuration includes: enabled (enable rate limiting, defaults: true in production, false in development); window (time window in seconds for rate limiting, default: 10); max (default maximum requests allowed within window, default: 100); customRules (custom rate limit rules for specific paths); storage ("memory", "database", or "secondary-storage", if secondary storage passed, rate limiting stored there, default: "memory"); modelName (table name for rate limiting if database used as storage, default: "rateLimit").

disabledPaths option

disabledPaths allows disabling specific auth paths. For example, ['/sign-up/email', '/sign-in/email'] would disable those authentication endpoints.

telemetry option

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

plugins option

The plugins option is a list of Better Auth plugins. Plugins are configured as an array and can extend functionality. Example shows emailOTP plugin with sendVerificationOTP configuration.

Give your agent this brain