Authentication

Configure OAuth providers and sign-in behavior

Account sign-in uses Better Auth. Configure the providers you want to offer, then supply their credentials. See Identity & Access for sessions, ownership, and optional guest access.

Enabling Providers

Toggle providers in chat.config.ts under the authentication key:

authentication: {
  google: false, // requires AUTH_GOOGLE_ID + AUTH_GOOGLE_SECRET
  github: true,  // requires AUTH_GITHUB_ID + AUTH_GITHUB_SECRET
  vercel: false, // requires VERCEL_APP_CLIENT_ID + VERCEL_APP_CLIENT_SECRET
},

Provider toggles in chat.config.ts control validation and which sign-in buttons are shown. Runtime provider registration in lib/auth.ts is based on provider env vars being present.

To fully disable a provider, set its toggle to false and remove its env vars.

Config validation runs at build time via bun run prebuild. A missing env var for an enabled provider fails the build. At least one provider must be enabled and fully configured.

Required environment variables

All providers also require a shared secret used to sign session tokens:

AUTH_SECRET=<random 32-byte base64 string>

Generate one:

openssl rand -base64 32
# or visit https://generate-secret.vercel.app/32

Provider Setup

GitHub

1. Go to GitHub → Settings → Developer Settings → OAuth Apps → New OAuth App.
2. Set Homepage URL to your app URL (e.g. https://your-domain.com).
3. Set Authorization callback URL to:

   https://your-domain.com/api/auth/callback/github

4. Copy the Client ID and generate a Client Secret.
5. Add to your environment:

   AUTH_GITHUB_ID=your_client_id
   AUTH_GITHUB_SECRET=your_client_secret

6. Enable in chat.config.ts: authentication: { github: true }

Google

1. Go to Google Cloud Console → APIs & Services → Credentials → Create Credentials → OAuth client ID.
2. Choose Web application.
3. Under Authorized redirect URIs add:

   https://your-domain.com/api/auth/callback/google
   http://localhost:3000/api/auth/callback/google

4. Copy the Client ID and Client Secret.
5. Add to your environment:

   AUTH_GOOGLE_ID=your_client_id
   AUTH_GOOGLE_SECRET=your_client_secret

6. Enable in chat.config.ts: authentication: { google: true }

Vercel

1. Create a Vercel App using the Sign in with Vercel setup guide.
2. Under Redirect URL add:

   https://your-domain.com/api/auth/callback/vercel

3. Copy the Client ID and Client Secret from the Vercel App.
4. Add to your environment:

   VERCEL_APP_CLIENT_ID=your_client_id
   VERCEL_APP_CLIENT_SECRET=your_client_secret

5. Enable in chat.config.ts: authentication: { vercel: true }

Adding a New OAuth Provider

Better Auth supports many OAuth 2.0 / OIDC providers (Discord, Twitter/X, Apple, LinkedIn, and more). To add one:

1. Add a provider flag to authenticationConfigObjectSchema and AUTHENTICATION_DEFAULTS in lib/config-schema.ts. Update the authentication selections in chat.config.ts.
2. Declare its credentials in lib/env-schema.ts and its requirements in authEnvRequirements in lib/config-requirements.ts so check-env validates enabled providers.
3. Add the provider to the explicit socialProviders return type and registration object in lib/auth.ts, using those credentials.
4. Add its ID and order to SOCIAL_AUTH_PROVIDER_ORDER in lib/social-auth.ts. Add its label and icon to AUTH_PROVIDER_METADATA in components/auth-providers.tsx. The existing button list then renders it using the Better Auth client.
5. Register the OAuth app with the provider, setting the redirect URI to /api/auth/callback/[provider].
6. Run your app’s type checks and bun run check-env, then verify sign-in and callback handling.

See the Better Auth OAuth guide for the social-provider configuration model, then choose a provider from the Authentication section of the Better Auth docs for provider-specific options.