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.

  1. In the Google Cloud console, create an OAuth client ID of type Web application.

  2. 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 (your SITE_URL)
  3. Locally, put the keys in apps/web/.env:

    apps/web/.env

    AUTH_GOOGLE_CLIENT_ID=1234.apps.googleusercontent.com
    AUTH_GOOGLE_CLIENT_SECRET=GOCSPX-...
  4. Deployed, set both as Worker secrets:

    pnpm --filter web exec void secret put AUTH_GOOGLE_CLIENT_ID
    pnpm --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:

  1. Add its keys to apps/web/env.ts (your file, not kit-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(),
    });
  2. 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',
    },
    };
  3. Put the logo in apps/web/public/images/oauth/ (SVG or WebP, square, about 36×36 px or larger; an SVG with width and height on its <svg>, not only a viewBox).

  4. Register https://<your SITE_URL>/api/auth/callback/discord at 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). Set name or logo in 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 with fill="#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 accountProvider says the email is verifiedResult
verifiedyesThe provider is linked to it, the user is signed in and the owner gets "A sign-in method was added"
verifiednoRefused (account_not_linked)
never verifiedeitherRefused (account_not_linked)
linked beforeeitherSigned 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):

CodeMessage
access_deniedThe user cancelled at the provider
account_not_linkedThe email has an account that can't be linked (above)
email_not_foundThe provider didn't share an email
email_not_verifiedThe 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 elseThe 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.