Source: https://www.brixit.io/docs/turnstile

# Cloudflare Turnstile

Turnstile is Cloudflare's alternative to a CAPTCHA. It checks that a visitor is a real person
without making them identify traffic lights, and in most cases without them noticing at all.

Brixit uses it for web and mobile login, registration and public lead forms. Each self-hosted
installation uses its own Cloudflare widget and stores its keys encrypted locally.

## Optional protection

A Cloudflare account is not required to use Brixit. With no local Turnstile keys configured,
web and mobile login remain available, and login rate limiting stays active. Integration keys
shows **Off (optional)** with setup guidance.

Starting with **2.2.27**, installations can upgrade without local Turnstile keys. Turnstile
will be off after that upgrade, and preflight reports this as a
warning rather than blocking it. Public forms will have no Turnstile challenge until you
configure your own widget.

A partial or unreadable local key pair still blocks an upgrade while protection is enabled.
Repair the pair or deliberately choose **Disabled** before retrying.

## What you need

A Cloudflare account. You do not need your domain to be on Cloudflare's DNS — Turnstile works on
any site.

## Create a widget

1. In the Cloudflare dashboard, open **Turnstile** and press **Add widget**.
2. Give it a name and add your domain under **Hostname Management**.
3. Choose a widget mode. **Managed** is the right default: invisible to most visitors, with a
   checkbox only when Cloudflare is unsure.

Allow the hostname the widget will appear on, such as `crm.example.com`. Cloudflare also
authorizes subdomains of each hostname you add, so adding `example.com` allows its subdomains;
use the specific CRM hostname to keep the scope narrow.

See [Cloudflare hostname management](https://developers.cloudflare.com/turnstile/additional-configuration/hostname-management/).

## Fill in the fields

**Settings → Services & Credentials → Provided by your company → Cloudflare Turnstile**.

| Field | Where to find it |
| --- | --- |
| **Site Key** | Cloudflare dashboard, on your widget |
| **Secret Key** | Same widget, beside the site key |

The **Site Key** is public — it appears in the page source, which is expected. The **Secret Key**
is not, and is stored encrypted.

Choose **Bot protection**:

- **Use configured keys (default):** off when no local keys exist; on when keys are configured.
- **Enabled:** requires a complete, readable key pair.
- **Disabled:** skips Turnstile while retaining your saved keys. Login rate limiting remains active.

Saving only the mode does not erase your keys. A partial key pair in the default mode is treated
as enabled but incomplete; it never silently disables protection.

## Mobile app

After pairing with a workspace, the app retrieves its public site key and CRM origin. It runs
the Cloudflare challenge in an embedded browser using that origin and submits the token with
login. The secret stays on the CRM server, which verifies the token directly with Cloudflare.
No separate hostname is needed for each phone. When Turnstile is off, the app skips the challenge.

## Checking it works

Open your login page in a private window. The widget appears below the password field; in
managed mode it usually resolves on its own within a second.

If it shows an error code, Cloudflare's widget documentation lists them. `110200` means the
hostname is not on the widget's list.

## Turning it off

Select **Disabled** under Bot protection and save. This turns off challenges for web and mobile
login, registration and public lead forms, while retaining your saved keys for later use.
Choose **Enabled** again to restore protection.

You can also clear the stored configuration. If this server has installer-provided environment
keys, clearing the stored settings allows those keys to take effect; explicit **Disabled**
overrides them.
