Session Management

gau’s flexibility is achieved by supporting two primary session management strategies: cookie-based and token-based sessions.

Cookie-Based Sessions (Web Apps)

This is the most common method for full-stack web apps.

How It Works

1. Sign-In: The user is redirected to the OAuth provider.
2. Callback: After successful authentication, the provider redirects the user back to your apps’s callback URL (e.g., /api/auth/callback/github).
3. Session Cookie: gau validates the callback, creates a user session, and stores the session information in a secure, HttpOnly cookie.
4. Authenticated Requests: The browser automatically includes this cookie with every subsequent request to your backend. The server can then validate the cookie to identify the user.

This flow is handled automatically by the framework helpers, like @rttnd/gau/sveltekit.

The session cookie is named __gau-session-token by default and its attributes can be configured via the cookies option in createAuth.

---

Token-Based Sessions (Native Apps & SPAs)

Cookies don’t work well for desktop apps, mobile apps, or frontends hosted separately from the backend. For these cases, gau uses tokens instead.

How It Works

The flow uses PKCE to securely pass the session token from your backend to the app, ensuring only the app that started the login can receive the token.

1. Sign-In: The client-side signIn function generates a PKCE code_verifier and code_challenge. It opens the system’s web browser to the OAuth provider’s authorization URL, including the challenge.
2. Callback & Redirect: After the user approves, the provider redirects to your backend. The backend validates the request and issues a short-lived Auth Code via a deep link redirect (e.g., my-app://oauth/callback?code=...).
3. Exchange: The operating system captures this custom URL and re-opens your native app. The app extracts the auth code and sends it, along with the original code_verifier, to the backend’s /token endpoint.
4. Token Storage: Upon successful validation, the backend returns a session token. The client library stores it in:
   • localStorage: For the client to attach it to subsequent API requests in the Authorization: Bearer <token> header.
   • A non-HttpOnly cookie: This allows server-side rendering logic to access the session on the initial page load.
5. Authenticated Requests: The client now includes this token in the Authorization header for all subsequent API requests.

This is entirely managed by gau. The client libraries automatically handle storing the token and including it in requests, while the backend is designed to render the necessary redirect page.

See the Tauri integration guide for a practical example.

Session Strategy

You can control this behavior using the session.strategy option in createAuth.

• 'auto' (Default): gau automatically switches between cookie-based and token-based sessions. It uses cookies by default but will switch to the token flow if it detects a redirect to a different host or a custom URL scheme.
• 'cookie': Forces cookie-based sessions, even for cross-origin redirects (as long as the host is trusted).
• 'token': Forces token-based sessions, even for same-origin redirects.