For the complete documentation index, see llms.txt. Prefer markdown by appending.mdto documentation URLs or sendingAccept: text/markdown.
OAuth providers
Connect Google, GitHub, and Cloudflare sign-in, register the correct callback URLs, and understand trusted account linking in Edge Kit.
Each OAuth provider needs two things: a button in authConfig.providers.oAuth and credentials in the Better Auth server configuration. The kit wires Google, GitHub, and Cloudflare in both places by default.
Callback origin
Use BETTER_AUTH_URL, not the marketing site's URL, as the callback origin:
| Provider | Callback path | Credentials |
|---|---|---|
/api/auth/callback/google | Google OAuth client | |
| GitHub | /api/auth/callback/github | GitHub OAuth app |
| Cloudflare | /api/auth/callback/cloudflare | Cloudflare OAuth client |
For a local app at http://localhost:3000, Google's complete callback is http://localhost:3000/api/auth/callback/google. Register the production callback separately when the provider supports multiple origins, otherwise create a separate local OAuth app. Keep local and production credentials matched to the callback each uses.
Cloudflare's OAuth client setup uses the user-details.read scope and the client_secret_basic token authentication method. Follow its provider setup for account and redirect restrictions.
Environment variables
Set the credential pair listed in auth configuration. For GitHub, for example:
GITHUB_CLIENT_ID="<your-github-client-id>"
GITHUB_CLIENT_SECRET="<your-github-client-secret>"Keep SocialProvider.GITHUB in src/config/auth.ts. Restart local development after changing credentials. In production, store the pair as Wrangler secrets for your Worker and deploy the updated configuration.
Removing the button only changes the view. To disable the provider's API, also remove its entry from socialProviders in src/lib/auth/server.ts.
Account linking
account.accountLinking.enabled is true, and trustedProviders uses the OAuth provider array from authConfig. This lets Better Auth apply its account linking rules to the providers you trust.
Review that trust decision before adding another provider. Do not assume an arbitrary provider's email claim has the same guarantees as the shipped providers. Existing users can view and manage linked accounts at /dashboard/settings/security.
Custom providers
Adding credentials alone is not enough. Extend the provider constants and validation in src/modules/auth/lib/schema.ts and src/modules/auth/lib/config.ts, add the server provider, and update the social provider view under src/modules/auth/form/. Add its labels to both message catalogs and configure its callback in the provider dashboard.
Use Better Auth's supported providers to implement that provider's exact configuration. The kit does not ship buttons or wiring for every provider Better Auth supports.
Troubleshooting
To check the full flow and verify the callback, open /auth/login, select the provider, complete consent, and confirm you return to the app on the expected origin. Check the account in security settings and try linking an existing account deliberately.
If the callback fails, compare the registered URL character-for-character with BETTER_AUTH_URL plus the callback path. Check the provider credentials, allowed origin, and Worker logs before changing the route. See local development troubleshooting.
How is this guide?
Last updated on