# Bot protection

Bot protection guards the [hosted login](/user-management/hosted-login/) against credential stuffing, fake sign-ups and account takeover. Configure it with `GET` and `PUT /v1/user_management/bot_protection` (`users:read` / `users:write`) or `ohauthcat bot-protection get|set`.

## CAPTCHA

OhAuthCat uses Cloudflare Turnstile, verified on the server.

| Setting            | Values                                                                                                                                 |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
| `captcha_mode`     | `off`; `adaptive` (always on sign-up, on sign-in after 5 failures from a client or 3 for an address in 15 minutes); `always`           |
| `captcha_provider` | `managed` (OhAuthCat's widget) or `own` (your `turnstile_site_key` and `turnstile_secret`; the secret is encrypted and never returned) |

Each challenge works once and is bound to the browser, the flow and the environment. If Turnstile cannot be reached, sign-up stops (fail closed) and sign-in continues. A failed challenge answers [`bot_challenge_failed`](/errors/bot_challenge_failed/).

## Device signals

With `device_tracking` on, a first-party cookie (random, 400 days) combined with the browser and network is kept only as a keyed digest. It powers the `unrecognized_device` rule and, with `new_device_email`, an email to the user after a sign-in from a new device. No third-party script runs.

## Rules

Rules run in order; the first enabled match decides. Actions are `allow` (stop evaluating, for example to exempt an office network), `deny` or `challenge` with `captcha` or `mfa`.

| Kind                                             | Matches                                                                         |
| ------------------------------------------------ | ------------------------------------------------------------------------------- |
| `country`                                        | Country in the list (or, with `not_in`, outside it; an unknown country matches) |
| `ip`                                             | Client address in one of the CIDR ranges                                        |
| `asn`                                            | Network operator (ASN) in the list                                              |
| `email_domain`                                   | The address's domain or a parent domain                                         |
| `disposable_email`                               | A known disposable-email domain                                                 |
| `sign_up_velocity_ip`, `sign_up_velocity_domain` | More than `threshold` sign-ups from one network or for one domain in the window |
| `repeat_sign_up`                                 | The same mailbox signing up again (case, `+tag` and Gmail dots ignored)         |
| `stale_account`                                  | No sign-in for more than `days` (after the first factor)                        |
| `unrecognized_device`                            | A device the user has not used before (after the first factor)                  |

Rules after the first factor can only deny or ask for MFA. Passkey and social sign-in starts run the deny rules only. A blocked attempt answers [`sign_in_blocked`](/errors/sign_in_blocked/).

Decisions use only the client address resolved at the edge; forwarded-for headers sent by the client never move an attempt into or out of a rule.

## Detections

Every challenged or blocked attempt is stored for 90 days: `GET /v1/user_management/bot_detections` or `ohauthcat bot-protection detections`. It also emits `user.sign_in.challenged` or `user.sign_in.blocked` with the rule, reasons, email domain, country and ASN, never a full email or address.

Which parts each plan includes is not final; the pricing page is the source for it.
