Cookies & Bearer

AuthFort supports two token delivery modes. Choose based on your application type.

Cookie Mode

Tokens are delivered as HttpOnly cookies. The browser handles them automatically — no JavaScript ever touches the tokens.

from authfort import AuthFort, CookieConfig

auth = AuthFort(
    database_url="...",
    cookie=CookieConfig(),
)

from authfort import AuthFort, CookieConfig

auth = AuthFort(
    database_url="...",
    cookie=CookieConfig(),
)

Best for: Web applications, SPAs with same-origin or subdomain APIs.

CookieConfig Options

CookieConfig(
    secure=True,                        # HTTPS only (disable for localhost)
    httponly=True,                       # No JavaScript access
    samesite="lax",                     # "lax", "strict", or "none"
    path="/",                           # Cookie path
    domain=None,                        # Cookie domain (e.g., ".example.com")
    access_cookie_name="access_token",  # Access token cookie name
    refresh_cookie_name="refresh_token", # Refresh token cookie name
)

CookieConfig(
    secure=True,                        # HTTPS only (disable for localhost)
    httponly=True,                       # No JavaScript access
    samesite="lax",                     # "lax", "strict", or "none"
    path="/",                           # Cookie path
    domain=None,                        # Cookie domain (e.g., ".example.com")
    access_cookie_name="access_token",  # Access token cookie name
    refresh_cookie_name="refresh_token", # Refresh token cookie name
)

Subdomain Cookies

To share auth across subdomains (e.g., app.example.com and api.example.com):

cookie=CookieConfig(domain=".example.com")

cookie=CookieConfig(domain=".example.com")

The leading dot allows all subdomains to read the cookie.

Local Development

For http://localhost, disable secure:

cookie=CookieConfig(secure=False)

cookie=CookieConfig(secure=False)

Bearer Mode

Tokens are returned in the response body and sent via the Authorization: Bearer header. No cookies involved.

auth = AuthFort(
    database_url="...",
    # No cookie= parameter → bearer-only mode
)

auth = AuthFort(
    database_url="...",
    # No cookie= parameter → bearer-only mode
)

Best for: Mobile apps, desktop apps, APIs consumed by non-browser clients.

In bearer mode, the client is responsible for storing the refresh token. The client SDK provides a TokenStorage interface for this. See Bearer Storage for setup details.

Which Should I Use?

Scenario	Mode	Why
React/Vue/Svelte SPA	Cookie	Simplest — browser handles everything
Same-origin API + frontend	Cookie	No CORS issues, automatic credentials
Subdomain architecture	Cookie with domain	Share auth across app.x.com and api.x.com
React Native / mobile	Bearer	No browser cookies available
Electron / desktop	Bearer	No browser cookies
Third-party API consumers	Bearer	Cookies don’t work cross-origin
Microservice-to-microservice	Bearer	Server-side token passing

Both Modes Together

AuthFort can serve both modes simultaneously. When cookie is configured:

• If the request has cookies, tokens are read from and written to cookies
• If the request has an Authorization: Bearer header, that token is used instead
• Login/refresh responses include both cookies and the JSON body with tokens

This means a single auth server can serve both a web frontend (cookies) and a mobile app (bearer).