Authdog can require a Google reCAPTCHA check on its hosted authentication flows, cutting off automated sign-up, credential stuffing, and one-time-code abuse at the front door. It is configured per environment as an add-on, so development and production can run different keys — or no protection at all.

Bot protection filters traffic before it authenticates. It complements, but does not replace, [Lidar](/docs/concepts/lidar) detections and rate limiting.

## Enable reCAPTCHA

Create a reCAPTCHA site in the [Google reCAPTCHA admin console](https://www.google.com/recaptcha/admin) first, and add the domain that serves your Authdog authentication pages. Then, in the [Authdog console](https://console.authdog.com):

1. Select the project and environment.
2. Open **Authentication > Add-ons**.
3. Select **Google reCAPTCHA**.
4. Choose the version: **v3** (score-based, invisible) or **v2** (checkbox challenge).
5. Enter the **site key** and the **secret key**.
6. For v3, set the minimum score to accept.
7. Select which auth flows to protect.
8. Enable the add-on and save.

The add-on cannot be enabled without a site key. The site key is public and is rendered on the auth pages; the secret key is encrypted at rest, never returned to the browser, and is only decrypted server-side to verify tokens.

## Protected flows

You can attach a check to any of these actions:

| Action | Flow |
| --- | --- |
| `signin` | Email and password sign-in |
| `signup` | Email and password sign-up |
| `waitlist` | Waitlist registration |
| `magic_link` | Magic link request |
| `otp_verify` | One-time code verification |
| `otp_resend` | One-time code resend |
| `mfa_verify` | MFA challenge verification |

Selecting no actions protects all of them — an enabled add-on defaults to its broadest coverage.

Only the `signin`, `signup`, and `waitlist` pages can render a visible checkbox, so those are the only actions **v2** protects. The rest need a token issued without a visible challenge, which means **v3**.

## v2 versus v3

**v3** scores every request from `0.0` (likely a bot) to `1.0` (likely a person) without any user interaction, and Authdog rejects requests scoring below your configured minimum. The default minimum is `0.5`; a value outside `0.0`–`1.0` falls back to it. When Google echoes an action name, Authdog also requires it to match the flow being attempted, so a token minted on one page cannot be replayed on another.

**v2** shows the "I'm not a robot" checkbox and returns a pass or fail with no score. Use it when you want a visible, explainable challenge on your sign-in and sign-up pages.

Start v3 at a permissive minimum, watch how real traffic scores, and tighten from there. Set the bar too high and you reject legitimate users on shared networks and privacy-hardened browsers.

## Verification behavior

Authdog verifies every token server-side against Google's `siteverify` endpoint, forwarding the client IP when it is known.

The check **fails closed** when a token is missing or Google reports it invalid, when a v3 score is under the minimum, or when the echoed action does not match. The user sees a verification error and the attempt does not proceed.

The check **fails open** when the add-on is enabled but the secret key is missing or cannot be decrypted. A configuration mistake must not lock every user out of an environment, so the flow continues without a CAPTCHA. Verify a new configuration with a real sign-in in a non-production environment rather than assuming that "enabled" means "enforcing".

## Rollout

1. Configure and test in development first.
2. Enable v3 on `signup` and `waitlist` — the flows attackers hit first.
3. Add `signin`, `magic_link`, and the one-time-code actions once real-traffic scores look healthy.
4. Repeat in production with production-specific keys. Keys are per environment and are not copied between them.

Confirm your reCAPTCHA site lists every domain that serves your auth pages, including any [custom domain](/docs/custom-domains). A domain mismatch makes Google reject every token, and every protected attempt then fails closed.

## Related

- [Lidar threat detection](/docs/concepts/lidar)
- [Multi-factor authentication](/docs/mfa)
- [Security](/docs/security)
- [Custom domains](/docs/custom-domains)