Custom cookies configuration example
Example of customizing session_token cookie: betterAuth({ advanced: { cookies: { session_token: { name: "custom_session_token", attributes: { } } } } })
Better Auth · Concepts · all subjects
cookies
21 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.
Cookie signing with secret key
All cookies in Better Auth are signed using the secret key provided in the auth options or the BETTER_AUTH_SECRET environment variable. If versioned secrets are used for rotation, encrypted cookie data such as JWE session caches will automatically use the current key and remain decryptable with previous keys.
Default cookie prefix format
Better Auth cookies follow the format ${prefix}.${cookie_name}. The default prefix is 'better-auth'.
Customize cookie prefix
You can change the cookie prefix by setting cookiePrefix in the advanced object of the auth options.
Default cookie attributes in production
All cookies are httpOnly and secure when the server is running in production mode.
Default cookies used by Better Auth
Better Auth uses the following default cookies: session_token to store the session token, session_data to store the session data if cookie cache is enabled, and dont_remember to store the flag when rememberMe is disabled. Plugins may also use cookies to store data, such as the Two Factor Authentication plugin which uses the two_factor cookie.
Customize cookie names and attributes
You can set custom cookie names and attributes by configuring the cookies object in the advanced section of auth options. Each cookie can have a custom name and attributes property.
Cross-subdomain cookies domain security guidelines
When enabling cross-subdomain cookies: 1) Only enable if necessary, 2) Set the domain to the most specific scope needed (e.g., app.example.com instead of .example.com), 3) Be cautious of untrusted subdomains that could access these cookies, 4) Consider using separate domains for untrusted services (e.g., status.company.com vs app.company.com).
Enable cross-subdomain cookies
To share cookies across subdomains, enable crossSubDomainCookies in the advanced object with enabled: true and set the domain property to your target domain (e.g., app.example.com).
Force secure cookies in development
You can force cookies to always be secure by setting useSecureCookies to true in the advanced object of auth options, even when not in production mode.
Safari Intelligent Tracking Prevention blocks third-party cookies
Safari's Intelligent Tracking Prevention (ITP) feature blocks third-party cookies. If Better Auth API is hosted on a different domain than the frontend, Safari may block authentication cookies entirely, resulting in sessions not persisting, Set-Cookie being ignored, users appearing logged out after login, or auth working in Chrome but failing in Safari.
Solve Safari ITP with reverse proxy
Instead of calling the API directly from a different domain, use a reverse proxy to proxy requests through the same domain as the frontend. This makes the request appear first-party to Safari, allowing cookies to function correctly. For example, proxy requests to /api/* to https://domainA.com/api/:splat.
Netlify reverse proxy configuration
Example of configuring a reverse proxy in Netlify: [[redirects]] from = "/api/*" to = "https://domainA.com/api/:splat" status = 200 force = true
Vercel reverse proxy configuration
Example of configuring a reverse proxy in Vercel: { "rewrites": [ { "source": "/api/:path*", "destination": "https://domainA.com/api/:path*" } ] }
Solve Safari ITP with shared parent domain
You can avoid Safari treating the API as third-party by using a shared parent domain for both frontend and API (e.g., app.example.com and api.example.com), then enable cross-subdomain cookies with the parent domain (example.com).
Cross-subdomain cookies with shared parent domain example
Example configuration for shared parent domain: betterAuth({ advanced: { crossSubDomainCookies: { enabled: true, domain: "example.com" } } })
Cookie cache strategy types
Better Auth supports three cookie cache encoding strategies: compact (default, uses base64url encoding with HMAC-SHA256, smallest size, good security, readable, not interoperable, best for performance), jwt (standard JWT with HMAC-SHA256, medium size, good security, readable, interoperable, for JWT compatibility), jwe (uses JWE with A256CBC-HS512 and HKDF key derivation, largest size, best security, not readable, interoperable, for maximum security).
Cookie cache enables session validation without database queries
Cookie caching stores session data in a short-lived, signed cookie similar to how JWT access tokens are used with refresh tokens. When enabled, the server can check session validity from the cookie itself instead of hitting the database each time. The cookie is signed to prevent tampering.
Cookie cache revocation delay caveat
When cookieCache is enabled, revoked sessions may remain active on other devices until the cookie cache expires (maxAge). This is because cookie cache stores session data in the client's browser and the server cannot directly delete cookies from other devices. Sessions are only revalidated when the cache expires or disableCookieCache: true is used.
refreshCache option behavior
The refreshCache option in cookieCache controls automatic cookie refresh before expiry without querying a database. When false (default), no automatic refresh occurs. When true, enables automatic refresh with default settings (refreshes at 80% of maxAge, 20% time remaining). When an object, allows custom refresh configuration with updateAge property specifying seconds remaining before expiry when refresh occurs.
Versioning stateless sessions for invalidation
To invalidate all stateless sessions in Better Auth, change the version of the cookie cache and redeploy your application. Set the version property in the cookieCache configuration. This will invalidate all sessions that don't match the new version.