Skip to main content
theAuth only sets cookies when you use its human-auth session features. If Clerk, Auth.js, or better-auth runs your sign-in, theAuth is cookie-free, it authenticates agents with bearer tokens instead. Cookie handling is configured on the cookie session manager (createCookieSessionManager, exported from @glinr/theauth), not through a top-level cookies option on createTheAuth. See Sessions for the full manager API.

Defaults

Secure is on by default and does not depend on NODE_ENV, which is unset or different on Cloudflare Workers, Deno and Bun. Every Set-Cookie from core goes through one serializer (serializeCookie in @glinr/theauth/session), so the rule is the same everywhere.
  • Without a request, the cookie is Secure.
  • resolveCookieSecure(request, { trustProxy }) (or serializeCookie(..., { request })) gives Secure for https URLs and for x-forwarded-proto: https when the proxy is trusted (trustProxy: true, or trustedProxyCount / trustedHeader set). Untrusted forwarded headers are ignored.
  • It gives no Secure only for plain http://localhost, 127.0.0.1, [::1] or *.localhost during development, or when you pass secure: false explicitly.
Chrome and Firefox accept Secure cookies on http://localhost, so the default also works for local development. Safari does not, so pass secure: false there or use https.

Prefixes and attribute checks

The serializer throws on combinations browsers reject: a __Host- cookie must be Secure, Path=/ and have no Domain; a __Secure- cookie must be Secure; Partitioned and SameSite=None require Secure.

Overriding

cookieOptions accepts httpOnly, secure, sameSite, path, domain, expires and partitioned. maxAge comes from the top-level maxAge option.
Changing the cookie name on a live app signs every user out on the next request. Do it during a planned migration window or ship a middleware that reads both names for a transition period.

Cross-subdomain

Share sessions across app.example.com and auth.example.com by setting a leading-dot domain.
A leading dot is the shape browsers accept even if the spec no longer requires it. It is still the interoperable choice across every browser that matters.

Cross-origin (different registrable domains)

If your auth server and your app live on different registrable domains (auth.example.com and app.example.org), cookies are not enough. Use the JWT session path instead. Cookies do not cross registrable domains under any SameSite mode that browsers accept in 2026.

Sliding vs absolute expiry

By default (autoRefresh: true), every successful validateSession replaces the session row and returns a new cookie in refreshCookieHeader with a fresh Max-Age. A user signed in thirty days ago but still active stays signed in. Turn autoRefresh off to expire the session maxAge seconds after sign-in regardless of activity:
For sensitive actions you can additionally require a recently authenticated session, see session freshness in Sessions. Pass the raw Cookie header to validateSession. It returns { session, refreshCookieHeader }, where session is null when the cookie is missing, invalid, expired, or revoked.

Troubleshooting

You are probably changing the session secret. Session tokens are signed with it, and a new secret invalidates existing cookies. The session manager secret option takes a single string, so keep it stable across deploys. The stateless session cookies and the session cookie cache do support rotation: pass secret: [newSecret, oldSecret] (first signs, all verify) and remove the old entry after the cookie lifetime has passed. See Session hardening.
Some older mobile webviews treat Lax inconsistently across top-level POSTs. Set cookieOptions: { sameSite: 'none', secure: true } and make sure you are on HTTPS.

Sessions

Cookie and JWT session management with lifecycle details.

JWT sessions

Stateless access tokens for cross-origin and mobile setups.

Multi-session

List and revoke a user’s sessions.

Custom session fields

Store application-specific data inside every session.
Last modified on October 18, 2026