Vanilla Client
The vanilla client can be used with any frontend setup. It’s perfect for:
- Backend-only auth setups (Bun.serve, Elysia, etc.)
- Frameworks not yet supported by
gau - Frameworkless apps
-
Set up your backend
Section titled “Set up your backend”Follow one of the backend-only integration guides:
Or use
createHandlerfrom@rttnd/gau/corewith any framework that supports standardRequest/Responseobjects. -
Create the client
Section titled “Create the client”Import
createAuthClientand initialize it with your auth API base URL:src/auth.ts import process from 'node:process'import { createAuthClient } from '@rttnd/gau/client/vanilla'import type { Auth } from './server/auth'export const auth = createAuthClient<Auth>({baseUrl: process.env.AUTH_BASE_URL, // http://localhost:3000/api/auth in dev}) -
Use the client
Section titled “Use the client”The client provides methods to manage authentication:
Fetch Session
Section titled “Fetch Session”const session = await auth.fetchSession()console.log(session.user) // User | nullSign In
Section titled “Sign In”Redirects to OAuth provider
window.location.href = await auth.signIn('github', {redirectTo: '/dashboard', // Optional})Sign Out
Section titled “Sign Out”await auth.signOut()Link Account
Section titled “Link Account”window.location.href = await auth.linkAccount('google', {redirectTo: '/profile',})Unlink Account
Section titled “Unlink Account”await auth.unlinkAccount('google')Refresh Session
Section titled “Refresh Session”await auth.refreshSession()Use a Server Session
Section titled “Use a Server Session”Start with the safe session returned by your server helper:
const auth = createAuthClient({ baseUrl: '/api/auth', session })After navigation, apply fresh server data with
auth.setSession(session). This updates subscribers without making a request. To fetch current data from the server instead, useauth.refreshSession().Create shared clients only in browser code. On the server, keep each visitor’s session separate.
Listen to Session Changes
Section titled “Listen to Session Changes”const unsubscribe = auth.onSessionChange((session) => {console.log('Session updated:', session)// Update UI, store in state management, etc.})// Later: clean up listenerunsubscribe()Handle Redirect Callbacks
Section titled “Handle Redirect Callbacks”After OAuth redirects back to your app, handle the callback:
const handled = await auth.handleRedirectCallback((url) => {window.history.replaceState({}, '', url) // Example})if (handled) {console.log('OAuth callback handled, session updated')} -
Next Steps
Section titled “Next Steps”- Learn about Session Management
- Explore OAuth Providers
- See Security best practices
Session Token Storage
Section titled “Session Token Storage”For browser apps that use bearer tokens instead of session cookies, set credentials: 'omit':
const auth = createAuthClient({ baseUrl: 'https://auth.example.com/api/auth', credentials: 'omit',})Use the server’s default session.strategy: 'auto' or 'token'. Add the frontend host to trustHosts and allow its origin in CORS. Use an absolute frontend URL for redirectTo when the backend is on another origin.
Browser sign-in uses PKCE and stores the returned bearer token in localStorage under __gau-session-token. Call handleRedirectCallback() after returning to the app; framework providers do this on mount. Bearer-authenticated requests omit cookies.
Bearer account linking requires the adapter’s atomic verification store, supported by the built-in memory and Drizzle adapters. Navigate to the URL returned by linkAccount() promptly: it is single-use and expires after one minute.
API Reference
Section titled “API Reference”createAuthClient<TAuth>(options)
Section titled “createAuthClient<TAuth>(options)”Creates a new auth client instance.
Options:
baseUrl(required): Base URL of your auth APIcredentials: Fetch credentials mode; defaults to'include'in browsers and'omit'in Tauri
Returns:
fetchSession(): Fetches the current session from the serverrefreshSession(): Fetches the session, updates client state, and notifies subscribersapplySessionToken(token): Applies a session token manuallyonSessionChange(listener): Subscribes to session changes, returns unsubscribe functionhandleRedirectCallback(replaceUrl?): Handles OAuth redirect callbackssignIn(provider, options?): Initiates sign-in flowsignOut(): Signs out the userlinkAccount(provider, options?): Links an additional OAuth accountunlinkAccount(provider): Unlinks an OAuth account