Skip to main content
Use Better Auth when Overlay should own the web session in the customer deployment while delegating login to an enterprise OIDC identity provider. Better Auth accounts are separate from hosted WorkOS accounts; do not expect hosted Overlay chats, billing, or preferences to carry over.

​
Requirements

  • A Postgres database dedicated to Better Auth session/account data.
  • A deployed Overlay web origin, for example https://overlay.example.com.
  • An OIDC application in the customer’s IdP. Direct Google Workspace is the recommended first private-deployment flow.
  • Matching Convex environment variables for Better Auth JWT verification only when Convex is enabled. Postgres-only deployments do not need a Convex client or Convex credentials.
Keep the Better Auth Postgres database auth-scoped. It stores Better Auth users, sessions, and linked SSO accounts; it does not replace Convex app data. If the deployment is preparing Postgres app-data support, use OVERLAY_DATABASE_URL for app records and BETTER_AUTH_DATABASE_URL only for Better Auth state.

​
Environment

Set these on the Next.js/Overlay web runtime:
Generate the Better Auth secret with:
For local smoke tests, use http://localhost:3000 consistently for BETTER_AUTH_URL, BETTER_AUTH_JWT_ISSUER, BETTER_AUTH_JWT_AUDIENCE, BETTER_AUTH_JWKS_URL, and trusted origins.

​
IdP Callback URLs

Register these URLs in the OIDC app:
The final path segment must match BETTER_AUTH_CONNECTION_ID. Also register the app origin as an allowed web origin:
Follow the provider recipe instead of manually guessing issuer metadata:

​
Migrations

Run migrations before starting production traffic:
For local Docker Postgres:
Re-run the migration command whenever Better Auth plugins or schema-affecting options change.

​
Convex Verification

Convex verifies the short-lived Better Auth JWTs using the JWKS URL:
Set the same Better Auth JWT values in the Convex deployment environment:
If the audience or JWKS URL is wrong, authenticated Convex-backed API calls should fail closed instead of accepting the token.

​
Smoke Checklist

After configuration:
Then run the Better Auth flow:
  • /api/better-auth/jwks returns JWKS.
  • /api/auth/options exposes only the configured connection IDs and labels.
  • /api/auth/sso/workspace?redirect=%2Fapp%2Fchat redirects into the configured Better Auth SSO provider.
  • The SSO callback creates a Better Auth session cookie.
  • /api/auth/session returns authenticated: true.
  • /api/auth/convex-token returns a JWT.
  • Convex-backed app APIs accept the JWT.
  • Sign out clears the Better Auth session.
  • Account deletion removes Better Auth rows and does not merge with hosted WorkOS accounts.
Run the negative smoke with the Better Auth dev server running: