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, since app data always lives in Convex.
BETTER_AUTH_DATABASE_URL is used only for Better Auth state — application records always live in the Convex deployment.
Security updates
Use Better Auth 1.7.16 or a later patched release, and keepbetter-auth and
@better-auth/sso on matching versions. The
November 3, 2026 security release
fixes multiple authentication issues in earlier versions. Update using the committed
lockfile, rebuild, and redeploy every private deployment using Better Auth.
Overlay configures SSO, JWT, and Next.js cookie integration, not the Better Auth Expo
or Electron plugins associated with the critical mobile and high-severity desktop
advisories. Hosted WorkOS authentication is a separate provider. This does not remove
the need to keep the installed Better Auth packages patched.
Environment
Set these on the Next.js/Overlay web runtime: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:BETTER_AUTH_CONNECTION_ID.
Also register the app origin as an allowed web origin:
- Google Workspace
- Auth0
- Generic OIDC for Cognito, Okta, and Keycloak
Migrations
Run migrations before starting production traffic:Convex Verification
Convex verifies the short-lived Better Auth JWTs using the JWKS URL:Smoke Checklist
After configuration:/api/better-auth/jwksreturns JWKS./api/auth/optionsexposes only the configured connection IDs and labels./api/auth/sso/workspace?redirect=%2Fapp%2Fchatredirects into the configured Better Auth SSO provider.- The SSO callback creates a Better Auth session cookie.
/api/auth/sessionreturnsauthenticated: true./api/auth/convex-tokenreturns a JWT.- The app’s live Convex queries load (Convex accepts the JWT natively).
- Sign out clears the Better Auth session.
- Account deletion removes Better Auth rows and does not merge with hosted WorkOS accounts.