Bot Protection with Turnstile
Cloudflare Turnstile on sign-up, sign-in, password reset and emailed links and codes: keys, which endpoints it guards, the forms, CSP and testing.
Cloudflare Turnstile checks that a real browser fills the auth forms, usually without the user doing anything. It stops bots that create accounts, try passwords from many IPs or send emails to strangers, where the per-IP rate limits alone don't help.
Turn It On
- In the Cloudflare dashboard, go to Turnstile and add a widget for your domain (and
localhostfor local work). Use the Managed mode. - Set both keys:
apps/web/.env
TURNSTILE_SITE_KEY=0x4AAAAAAA...TURNSTILE_SECRET_KEY=0x4AAAAAAA...Deployed: TURNSTILE_SITE_KEY is public (the browser gets it). The secret is a Worker secret: pnpm --filter web exec void secret put TURNSTILE_SECRET_KEY.
Captcha is on when both are set. Setting only one makes every request answer 500, with the missing key named in the logs. With neither, Better Auth's captcha plugin isn't registered and the forms show no check.
Cloudflare's test keys: site key 1x00000000000000000000AA and secret 1x0000000000000000000000000000000AA always pass, and the widget says "For testing only". env.example lists them in a comment; e2e uses them.
What It Guards
| Endpoint | Form |
|---|---|
/api/auth/sign-up/email | Sign up with a password |
/api/auth/sign-in/email | Sign in with a password |
/api/auth/request-password-reset | Forgot password |
/api/auth/send-verification-email | "Send the link again" |
/api/auth/sign-in/magic-link | Send Email Link |
/api/auth/email-otp/send-verification-otp | Email me a code (and resend) |
Not guarded:
- OAuth: the provider checks the user.
- Passkeys: the device checks the user.
- Entering an email code, a 2FA code or a new password: each has its own attempt limits, and its code or link came from the user's inbox or device.
A request without a token gets 400 MISSING_RESPONSE. A token Cloudflare refuses, or one solved on another host than SITE_URL's (a site key can list several, e.g. staging and localhost), gets 403 VERIFICATION_FAILED. Cloudflare's test secrets skip the host check: their answers name example.com. If Cloudflare can't be reached within 10 seconds, the request fails (500 UNKNOWN_ERROR) rather than letting bots through. The forms show each as a message (auth.errors.*).
The list is CAPTCHA_PATHS in packages/better-auth/src/captcha.ts. Only browser requests to /api/auth/* are checked; auth.api.* calls from your server code are not.
The Forms
CaptchaProvider (in apps/web/pages/auth/layout.tsx) holds one Turnstile check per page, shown where the page renders <CaptchaWidget />. Every form on the page uses it:
- Each request takes a token of its own and sends it in Better Auth's
x-captcha-responseheader; then the widget solves a new one. A token works only once, also when the request fails, so two forms submitted together each wait for their own. - A submit before the check finishes waits for it (up to 30 seconds), so a fast user or an interactive challenge doesn't cause an error.
- When Turnstile can't load (an ad blocker, a network or CSP block, an unsupported browser) or errors, submits don't wait: they go without a token and the form says the check didn't load ("Reload the page and try again"). Captcha fails closed.
- The widget follows the app's theme and the browser's language (Turnstile errors on a locale it doesn't know). Sign-in and sign-up show it only when an email method is on: OAuth and passkeys don't use it.
A form of your own that calls a guarded endpoint wraps its call with useCaptcha() from @kit/auth/captcha:
const { withCaptcha } = useCaptcha();const { error } = await withCaptcha((fetchOptions) => authClient.signIn.email({ email, password, fetchOptions }),);Put it on a page under pages/auth/ (inside the provider), with <CaptchaWidget /> on the page. Without the widget the form's requests fail at once, and the console says no <CaptchaWidget /> on this page. To guard another endpoint, add its path to CAPTCHA_PATHS and wrap its form the same way.
Content Security Policy
apps/web/config/security.config.ts already allows https://challenges.cloudflare.com in script-src, frame-src and connect-src. Turnstile's script is loaded by the kit's own nonce'd script, which 'strict-dynamic' trusts, so the CSP keeps its nonce and needs nothing else (Content Security Policy).
Testing
packages/better-auth/src/__tests__/captcha.test.tsmocks Cloudflare's siteverify. It checks every guarded endpoint: no token is refused, a refused token is refused, and a good one goes through. It also checks the host rule, that the request fails when Cloudflare is down, that other endpoints are untouched, and the key pairing.- E2E runs every spec with the test keys (
SIGN_IN_METHOD_ENV), so every form goes through the real widget.captcha.spec.tscovers:- the widget shows on sign-in, sign-up and reset, without CSP violations;
- a sign-in submitted before the check finishes still works;
- the server refuses a request without a token.
- API calls in specs send
CAPTCHA_TEST_HEADERS. - The e2e fixture sends a made-up
cf-connecting-ipto the app, and strips it from requests to Cloudflare, which answers 403 to a browser that sends that header.