Configuration Options

This page documents the public configuration types in crates/core/src/config.rs.

AuthConfig

Field	Type	Default	Description
`secret`	`String`	empty until set	Signing/encryption secret; must be at least 32 characters
`app_name`	`String`	`"Better Auth"`	App name used by emails and cookie-related metadata
`base_url`	`String`	`"http://localhost:3000"`	Base URL for the auth service
`base_path`	`String`	`"/api/auth"`	Auth route mount prefix
`trusted_origins`	`Vec<String>`	`[]`	Origins trusted for CSRF/origin checks
`disabled_paths`	`Vec<String>`	`[]`	Routes that should behave as disabled
`session`	`SessionConfig`	see below	Session token and cookie behavior
`jwt`	`JwtConfig`	see below	Optional JWT behavior
`password`	`PasswordConfig`	see below	Password policy and Argon2 settings
`account`	`AccountConfig`	see below	OAuth/account-linking behavior
`email_provider`	`Option<Arc<dyn EmailProvider>>`	`None`	Global email provider
`advanced`	`AdvancedConfig`	see below	Advanced cookie, IP, and DB options

SessionConfig

Field	Type	Default	Description
`expires_in`	`chrono::Duration`	`7 days`	Session lifetime
`update_age`	`Option<chrono::Duration>`	`Some(1 day)`	Age threshold before refreshing a session
`disable_session_refresh`	`bool`	`false`	Disable automatic refresh entirely
`fresh_age`	`Option<chrono::Duration>`	`None`	Optional freshness window for sensitive actions
`cookie_name`	`String`	`"better-auth.session_token"`	Cookie name used for session transport
`cookie_secure`	`bool`	Derived from `base_url`	`true` for HTTPS URLs, `false` for HTTP URLs
`cookie_http_only`	`bool`	`true`	Prevent JavaScript access to the cookie
`cookie_same_site`	`SameSite`	`Lax`	SameSite policy
`cookie_cache`	`Option<CookieCacheConfig>`	`None`	Optional cookie-backed session cache

Refresh semantics:

update_age = Some(duration): refresh only when older than duration.
update_age = None: refresh on every access.
disable_session_refresh = true: never refresh automatically.

CookieCacheConfig

Field	Type	Default	Description
`enabled`	`bool`	`false`	Whether the cache is active
`max_age`	`chrono::Duration`	`5 minutes`	Max age before forcing a DB lookup
`strategy`	`CookieCacheStrategy`	`Compact`	Protection strategy for the cached payload

CookieCacheStrategy variants:

Compact
Jwt
Jwe

JwtConfig

Field	Type	Default	Description
`expires_in`	`chrono::Duration`	`1 day`	JWT lifetime
`algorithm`	`String`	`"HS256"`	Signing algorithm
`issuer`	`Option<String>`	`None`	JWT `iss` claim
`audience`	`Option<String>`	`None`	JWT `aud` claim

PasswordConfig

Field	Type	Default	Description
`min_length`	`usize`	`8`	Minimum password length
`require_uppercase`	`bool`	`false`	Require uppercase letters
`require_lowercase`	`bool`	`false`	Require lowercase letters
`require_numbers`	`bool`	`false`	Require digits
`require_special`	`bool`	`false`	Require special characters
`argon2_config`	`Argon2Config`	see below	Argon2 tuning

Argon2Config

Field	Type	Default	Description
`memory_cost`	`u32`	`4096`	Memory cost in KiB
`time_cost`	`u32`	`3`	Iteration count
`parallelism`	`u32`	`1`	Degree of parallelism

AccountConfig

Field	Type	Default	Description
`update_account_on_sign_in`	`bool`	`true`	Refresh stored OAuth account data during sign-in
`account_linking`	`AccountLinkingConfig`	see below	Account-linking behavior
`encrypt_oauth_tokens`	`bool`	`false`	Encrypt stored OAuth tokens
`store_account_cookie`	`bool`	`false`	Store account data in a cookie for OAuth token flows
`store_state_strategy`	`OAuthStateStrategy`	`Database`	Where to persist OAuth state
`skip_state_cookie_check`	`bool`	`false`	Skip callback cookie-state verification

AccountLinkingConfig

Field	Type	Default	Description
`enabled`	`bool`	`true`	Enable account linking
`trusted_providers`	`Vec<String>`	`[]`	Providers allowed to auto-link
`allow_different_emails`	`bool`	`false`	Allow linking accounts with different emails
`allow_unlinking_all`	`bool`	`false`	Allow unlinking the last linked account
`disable_implicit_linking`	`bool`	`false`	Only allow explicit linking via `link-social`
`update_user_info_on_link`	`bool`	`false`	Refresh user info when linking an account

OAuthStateStrategy variants:

Cookie
Database

AdvancedConfig

Field	Type	Default	Description
`ip_address`	`IpAddressConfig`	see below	Client IP extraction behavior
`disable_csrf_check`	`bool`	`false`	Disable request-origin / Fetch Metadata CSRF checks
`disable_origin_check`	`bool`	`false`	Skip callback / redirect target origin validation
`cross_sub_domain_cookies`	`Option<CrossSubDomainConfig>`	`None`	Share cookies across subdomains
`cookies`	`HashMap<String, CookieOverride>`	`{}`	Per-cookie overrides
`default_cookie_attributes`	`CookieAttributes`	all `None`	Default attributes applied to every cookie
`cookie_prefix`	`Option<String>`	`None`	Prefix applied to every cookie name
`database`	`AdvancedDatabaseConfig`	see below	Database-related defaults
`trusted_proxy_headers`	`Vec<String>`	`[]`	Headers trusted for real client IP extraction

IpAddressConfig

Field	Type	Default
`headers`	`Vec<String>`	`["x-forwarded-for", "x-real-ip"]`
`disable_ip_tracking`	`bool`	`false`

CrossSubDomainConfig

Field	Type	Description
`domain`	`String`	Parent cookie domain such as `".example.com"`

CookieAttributes

Field	Type	Default
`secure`	`Option<bool>`	`None`
`http_only`	`Option<bool>`	`None`
`same_site`	`Option<SameSite>`	`None`
`path`	`Option<String>`	`None`
`max_age`	`Option<i64>`	`None`
`domain`	`Option<String>`	`None`

CookieOverride

Field	Type	Default
`name`	`Option<String>`	`None`
`attributes`	`CookieAttributes`	all `None`

AdvancedDatabaseConfig

Field	Type	Default	Description
`default_find_many_limit`	`usize`	`100`	Default limit for "find many" queries
`use_number_id`	`bool`	`false`	Prefer numeric generated IDs instead of UUID-like IDs

Plugin configs such as EmailPasswordConfig, SessionManagementConfig, OrganizationConfig, PasskeyConfig, and TwoFactorConfig are documented in their plugin guides, because their behavior is best understood next to the routes they affect.