Set up OAuth sign-in

Create and verify a real account

Authentication means proving who is using the app. Start Postgres and run migrations using the database guide first, then leave the Web server running. Open http://localhost:3000/auth, choose email/password sign-up, enter your name, email and password, and submit. Keep EMAIL_PROVIDER=local for this first test.

When a flow requests an email code, open http://localhost:3000/mail-preview in another browser tab, find the most recent message for that address and copy its code back into the sign-in form. Request a fresh code if it expires. These messages stay in the local outbox; repeatedly checking an external inbox will not find them. Sign out, then sign in again to confirm the database-backed account works.

If sign-up reports a database connection or missing-table error, finish database setup instead of enabling social login. Google, GitHub, Apple, X and Microsoft buttons need their own provider application and callback settings; enable one only after its provider guide is complete. Better Auth is the shipped default engine and does not need a paid authentication account for local email sign-in.

• Start Postgres before creating an account
• Use and troubleshoot email sign-in codes
• Configure Google sign-in
• Add Google sign-in
• Add GitHub sign-in
• Add Apple sign-in

Choose enabled sign-in methods

The foundation includes email/password, OTP, and configurable social authentication. Better Auth owns identity and sessions, while the application composes provider configuration and transactional OTP delivery.

Enable only the social providers you have configured. Provider client secrets and the authentication secret stay on the server.

Connect identity to a workspace

Authenticated handlers resolve session state before accessing workspace records. Workspace provisioning must remain idempotent so replaying a lifecycle hook does not create duplicate ownership records.

Verify session behavior

Test sign-in, invalid or expired OTPs, single-use consumption, sign-out, and rejected anonymous access. Memory-adapter tests cover handler semantics; production database persistence and real provider callbacks need separate acceptance.

Setup and configuration

1. Set AUTH_SECRET to at least 32 random characters — openssl rand -hex 32 works.

2. In each provider's developer console, create an OAuth app and register the callback URL: {APP_URL}/api/auth/callback/<provider> under Better Auth (the default AUTH_PROVIDER). Use separate apps for local and production where the provider allows only one callback — docs/github-auth-setup.md walks the GitHub flow end to end.

3. Flip the provider's flag and set its client pair — AUTH_GOOGLE_ENABLED plus GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET, and the matching trio for Apple, GitHub, Microsoft, or Twitter. Enabling a flag without its credentials fails startup and names the missing variable.

4. Microsoft is the one callback that differs by engine: /api/auth/callback/microsoft under Better Auth, /api/auth/callback/microsoft-entra-id under Auth.js.

AUTH_SECRET=<at-least-32-random-characters>
AUTH_PASSKEY_ENABLED=true
EARLY_ACCESS_INVITE_ONLY=false

AUTH_GOOGLE_ENABLED=true
GOOGLE_CLIENT_ID=…
GOOGLE_CLIENT_SECRET=…

AUTH_GITHUB_ENABLED=true
GITHUB_CLIENT_ID=…
GITHUB_CLIENT_SECRET=…

# AUTH_APPLE_ENABLED / AUTH_MICROSOFT_ENABLED / AUTH_TWITTER_ENABLED
# follow the same pattern:
# MICROSOFT_CLIENT_ID=…  MICROSOFT_CLIENT_SECRET=…
# TWITTER_CLIENT_ID=…    TWITTER_CLIENT_SECRET=…

# Workspace connected accounts (Settings → Connections):
# CONNECTED_X_CLIENT_ID=          CONNECTED_X_CLIENT_SECRET=
# CONNECTED_GOOGLE_CLIENT_ID=     CONNECTED_GOOGLE_CLIENT_SECRET=
# CONNECTED_MICROSOFT_CLIENT_ID=  CONNECTED_MICROSOFT_CLIENT_SECRET=

# Callbacks to register (Better Auth):
#   {APP_URL}/api/auth/callback/google
#   {APP_URL}/api/auth/callback/apple
#   {APP_URL}/api/auth/callback/github
#   {APP_URL}/api/auth/callback/twitter
#   {APP_URL}/api/auth/callback/microsoft   (Auth.js: microsoft-entra-id)

Implementation workflow

Workspace external accounts are a different surface: the CONNECTED_X_*, CONNECTED_GOOGLE_*, and CONNECTED_MICROSOFT_* pairs feed Settings → Connections, and their callbacks live under {APP_URL}/api/accounts/{x|google|microsoft}/callback. An empty client id leaves that provider's connect flow disabled — don't reuse sign-in app credentials there.

Provider client secrets stay server-only, exactly like AUTH_SECRET — never in NEXT_PUBLIC_ or EXPO_PUBLIC_ variables.

Sign-in working? Continue to Set up AI.

Verification and troubleshooting

Test first-time sign-in, a returning session, a cancelled consent screen, and a disabled provider. A callback mismatch is the usual failure — the registered URL must match APP_URL and the engine's callback id exactly, and the app needs a restart after env changes.