OAuth Sign-In
Sign in with Google and other OAuth providers: credentials, redirect URIs, adding a provider, account linking and errors.
Users click "Continue with Google" on /auth/sign-in or /auth/sign-up, approve at Google, and come back signed in to next (or the app home). A new email gets an account on that first sign-in. The kit ships Google; any provider Better Auth supports takes one config entry.
Turn On Google
A provider is on when both of its keys are set; there's no separate switch.
In the Google Cloud console, create an OAuth client ID of type Web application.
Add the Authorized redirect URIs, one per address the app runs on:
http://localhost:5173/api/auth/callback/google(pnpm dev)http://localhost:4173/api/auth/callback/google(pnpm preview)https://app.example.com/api/auth/callback/google(yourSITE_URL)
Locally, put the keys in
apps/web/.env:apps/web/.env
AUTH_GOOGLE_CLIENT_ID=1234.apps.googleusercontent.comAUTH_GOOGLE_CLIENT_SECRET=GOCSPX-...Deployed, set both as Worker secrets:
pnpm --filter web exec void secret put AUTH_GOOGLE_CLIENT_IDpnpm --filter web exec void secret put AUTH_GOOGLE_CLIENT_SECRET
Sign-in with an ID token posted from the browser (Google One Tap and similar) is off (disableIdTokenSignIn: true); set disableIdTokenSignIn: false in an entry to use it.
Only one of the two set is a mistake, and it fails loudly: every request (every page, not only sign-in) answers 500 with OAuth provider "google" needs AUTH_GOOGLE_CLIENT_SECRET (or _CLIENT_ID) in the logs until both are set or both removed. The browser only learns which providers are on (config.auth.providers.oAuth, e.g. [{ id: 'google' }]); the keys stay on the server.
Add a Provider
Any of Better Auth's social providers works. Adding one touches only your app's files, so kit updates never conflict with it. E.g. Discord:
Add its keys to
apps/web/env.ts(your file, notkit-env.ts):apps/web/env.ts
import { defineEnv, string } from 'void/env';export default defineEnv({...kitEnv,AUTH_DISCORD_CLIENT_ID: string().optional(),AUTH_DISCORD_CLIENT_SECRET: string().optional(),});Add the entry in
apps/web/config/auth.config.server.ts→oAuthEntries. The key is Better Auth's provider id:apps/web/config/auth.config.server.ts
const oAuthEntries: OAuthProviderEntries = {google: { … },discord: {clientId: env.AUTH_DISCORD_CLIENT_ID,clientSecret: env.AUTH_DISCORD_CLIENT_SECRET,name: 'Discord',logo: '/images/oauth/discord.svg',},};Put the logo in
apps/web/public/images/oauth/(SVG or WebP, square, about 36×36 px or larger; an SVG withwidthandheighton its<svg>, not only aviewBox).Register
https://<your SITE_URL>/api/auth/callback/discordat the provider, and set the keys.
The button appears by itself, with the entry's name and logo. Provider options (scopes, Google's hd domain restriction, Microsoft's tenantId) go in the same entry; see Better Auth's page for the provider. The browser only gets each button's id, name and logo (config.auth.providers.oAuth), never the keys.
Names and Logos
- Shipped providers need neither: Google, GitHub, Microsoft, Apple, Facebook and X (
twitter) have a name and logo in the kit (packages/auth/src/oauth-provider-display.ts). Setnameorlogoin their entry to change them; don't edit the kit file. - No name: the button shows the id, capitalized (
discord→ "Discord"). - No logo, or one that fails to load: the button shows a generic sign-in icon, never a broken image.
- Dark mode: a black logo (GitHub, Apple, X) disappears on a dark background. Give it two images,
logo: { light: '/images/oauth/acme.svg', dark: '/images/oauth/acme-dark.svg' }, and the page shows the one for the current theme. Most brand marks (colored, like Google or Discord) read on both and need only one. For the dark variant, use the provider's official white mark from its brand assets; for a single-color SVG, a copy withfill="#fff"does it.
A new account needs an email the provider has verified: one it reports as unverified gets no account (email_not_verified), since whoever holds that provider account could otherwise keep a way into the address's account after its owner verifies it. Google, GitHub, Microsoft, Apple, Discord and X report it; Facebook usually doesn't, so its new users are refused. To trust such a provider anyway, set emailVerified: true in its entry's mapProfileToUser, knowing the risk above.
Account Linking
When the provider's email already has an account, Better Auth's defaults decide:
| Existing account | Provider says the email is verified | Result |
|---|---|---|
| verified | yes | The provider is linked to it, the user is signed in and the owner gets "A sign-in method was added" |
| verified | no | Refused (account_not_linked) |
| never verified | either | Refused (account_not_linked) |
| linked before | either | Signed in |
Signed-in users link a provider from Settings → Security instead (Security): that flow allows a different email (allowDifferentEmails) because the signed-in session, fresh, is the proof of ownership. The option is not read when signing in.
The kit trusts no provider by name (trustedProviders is empty), so linking always needs both sides verified. An unverified account could belong to someone who registered the address in advance; linking would hand them the real owner's sign-in. The owner sees "An account with this email already exists…", and can sign in with email, or sign up again to replace the unverified account (see Overview).
Provider tokens are stored encrypted with BETTER_AUTH_SECRET (account.encryptOAuthTokens).
Errors
A failed or cancelled sign-in returns to /auth/sign-in?next=…&error=<code>, and the page shows a translated message (auth.oauth.* in packages/i18n/src/messages/en/auth.json):
| Code | Message |
|---|---|
access_denied | The user cancelled at the provider |
account_not_linked | The email has an account that can't be linked (above) |
email_not_found | The provider didn't share an email |
email_not_verified | The provider hasn't verified the email, so no account is created |
state_not_found, state_mismatch, … | The sign-in session expired or came from another browser: start again |
| anything else | The generic error |
The code table is callbackErrorKey in packages/auth/src/errors.ts. The provider's error_description is never shown: the provider (or whoever crafts the link) controls its text. A callback that fails before Better Auth knows the page to return to (no state) lands on /auth/sign-in too, not on Better Auth's own /api/auth/error.
/sign-in/social is limited to 10 a minute per IP.
Testing
Unit tests in packages/better-auth/src/__tests__/oauth.test.ts run the whole callback against a mocked Google token endpoint: a new user, an unverified email, linking, both linking refusals, cancel and a forged callback. E2E runs with fake Google keys (SIGN_IN_METHOD_ENV in tooling/scripts/src/preview-env.mjs) and stops at Google: it checks the buttons, the redirect (client id, callback, state) and the cancelled callback. A real sign-in needs real keys; try it with pnpm dev and your own Google client.