Secure core authentication flows
Protect email registration and login from automated abuse.
Better Auth · Const
captcha
The Better Auth captcha plugin adds bot protection to selected authentication endpoints. It supports several CAPTCHA providers and validates submitted tokens server-side.
How it works
The captcha plugin adds server-side bot verification to selected Better Auth routes. It validates tokens with the configured provider and blocks requests when verification fails or the provider is unavailable.
Syntax
captcha({ provider, secretKey, endpoints })Parameters
| Name | Type | Description |
|---|---|---|
provider | string | CAPTCHA provider name, such as cloudflare-turnstile, google-recaptcha, hcaptcha, captchafox, or vercel-botid. |
secretKey | string | Provider secret used for server-side validation; not required for Vercel BotID. |
endpoints | string[] | Optional list of request paths requiring CAPTCHA; supplying it replaces the defaults. |
Key points
- Use the plugin to add CAPTCHA checks to important authentication routes.
- The documented providers are Google reCAPTCHA, Cloudflare Turnstile, hCaptcha, CaptchaFox, and Vercel BotID.
- CAPTCHA runs as middleware before requests reach the selected authentication handlers.
- With no custom route list, email registration, email login, and password-reset requests receive protection.
- Clients must send the provider-generated token when calling protected routes.
Common mistakes
- Providing
endpointsreplaces the built-in protected routes, so list all routes that should require CAPTCHA. - Do not add the old remote-IP header; the server detects the client IP automatically.
Example: Enable CAPTCHA protection
import { betterAuth } from "better-auth";
import { captcha } from "better-auth/plugins";
export const auth = betterAuth({
plugins: [
captcha({
provider: "cloudflare-turnstile",
secretKey: process.env.TURNSTILE_SECRET_KEY!,
}),
],
});Configures the CAPTCHA plugin with Cloudflare Turnstile and a server-side secret key.
When to use it
Protect custom authentication endpoints
Apply CAPTCHA to authentication routes beyond the default email/password paths.
Centralize bot verification
Use a managed CAPTCHA service while keeping provider validation on the server.
Interview questions
QWhat does the captcha plugin do?
captcha is a Better Auth plugin that adds bot protection to authentication endpoints. It validates CAPTCHA tokens server-side for configured routes before allowing the request to proceed.
Follow-up: How are routes selected? By default, email sign-up, email sign-in, and password-reset requests are protected; supplying endpoints replaces that default list.
QWhat configuration does the plugin require?
The required provider selects the CAPTCHA service, while secretKey supplies the credential used for server-side validation. Supported providers include Google reCAPTCHA, Cloudflare Turnstile, hCaptcha, CaptchaFox, and Vercel BotID.
Follow-up: Which provider exception affects configuration? Vercel BotID does not require secretKey, unlike the other listed providers.
QWhich endpoints are protected by default?
The default configuration protects /sign-up/email, /sign-in/email, and /request-password-reset. Other authentication methods require explicitly configuring the endpoints option.
Follow-up: What happens when endpoints is configured? The default routes are no longer implicitly protected, so every desired protected path must be included.
Related
betterAuthpluginsendpointsprovidersecretKey