# Cloudflare Turnstile

Cloudflare Turnstile can be enabled to reduce automated enrolments and scripted abuse. When enabled, the enrolment form includes a Turnstile check and validates the resulting token server-side.

The implementation stays mostly invisible. Turnstile runs in the background and only becomes interactive when Cloudflare requires extra verification.

{% hint style="warning" %}
Bot detection cannot be 100% accurate. Turnstile provides basic bot mitigation, not a guarantee. AI-assisted automation and human-in-the-loop services make abuse increasingly hard to fully control. Cloudflare documents Turnstile’s approach here: [Cloudflare Turnstile docs](https://developers.cloudflare.com/turnstile/).
{% endhint %}

<div data-with-frame="true"><figure><img src="https://3566051324-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWLc8AHXW4tdrAXUBfrYF%2Fuploads%2FCYhWE7h3vlyk2uDQXaHB%2Fimage.png?alt=media&#x26;token=c7ac9dc5-c7cd-47fc-83c6-3fdc261fa4c0" alt="Turnstile challenge displayed as a modal during enrolment" width="375"><figcaption><p>Extra verification needed</p></figcaption></figure></div>

## How it works

1. When the enrolment form loads, Turnstile runs in the background.
2. When the form is submitted, Turnstile may ask for an interactive check.
3. The Wallet Crew validates the Turnstile token server-side before accepting the enrolment.

## Configuration

Configuration requires a Turnstile widget in Cloudflare and the widget keys. The Wallet Crew uses the **Site key** and **Secret key** to validate enrolment submissions.

{% stepper %}
{% step %}

### Create and configure a Turnstile widget in Cloudflare

Create a Turnstile widget in the Cloudflare dashboard. Cloudflare provides a **Site key** (public) and a **Secret key** (private) for each widget.

* Official setup guide: [Cloudflare Turnstile “Get started”](https://developers.cloudflare.com/turnstile/get-started/)
* Cloudflare dashboard entry point: [dash.cloudflare.com](https://dash.cloudflare.com/) (then open **Turnstile**)

**The default configuration is usually sufficient. Please consult your IT team for any additional adjustments.**
{% endstep %}

{% step %}

### Retrieve the Site key and Secret key

In Cloudflare, open the widget configuration and copy:

* **Site key**
* **Secret key**

These values are required in The Wallet Crew Back Office.
{% endstep %}

{% step %}

### Enable Turnstile in The Wallet Crew

Ask The Wallet Crew team to enable the Cloudflare Turnstile extension for the tenant.

Then open the Back Office settings page and paste the keys:

<p align="center"><a href="https://admin.thewalletcrew.io/tenant/~/settings/security/turnstile" class="button secondary" data-icon="chevrons-right">Turnstile settings</a></p>

<div data-with-frame="true"><figure><img src="https://3566051324-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWLc8AHXW4tdrAXUBfrYF%2Fuploads%2FFsNQGIZkktF7nFaJsuLm%2Fimage.png?alt=media&#x26;token=99b492e8-257f-48fd-be96-7d08d17c821e" alt="Turnstile settings in the Back Office." width="563"><figcaption><p>Turnstile settings in the Back Office.</p></figcaption></figure></div>
{% endstep %}
{% endstepper %}

## Notes

Turnstile is usually invisible because it runs in the background. An interactive check is only shown when Cloudflare flags the session as higher risk.

Token validation is always performed server-side by The Wallet Crew when the extension is enabled.

### Limits and expectations

Turnstile improves baseline protection, but it does not “solve bots”. Automated abuse evolves quickly and often relies on AI-assisted tooling, residential proxies, and human-in-the-loop services. This makes perfect bot detection unrealistic for most public enrolment flows.

Cloudflare positions Turnstile as a frictionless alternative to CAPTCHAs, not as a guarantee that every bot will be blocked. Combine Turnstile with other controls when enrolment is business-critical.

Official documentation: [Cloudflare Turnstile docs](https://developers.cloudflare.com/turnstile/)

### Challenge cookie

After a successful Turnstile verification, the application can set a short-lived security cookie. This keeps bot-protection state between requests and reduces repeated Turnstile challenges during the same enrolment session.

How this cookie works:

1. The user submits the enrolment form with a valid Turnstile token.
2. The server validates that token with Cloudflare.
3. If validation succeeds, the server issues a signed proof cookie.
4. On the next enrolment-related requests, the server checks that cookie.
5. If the cookie is still valid, the server can skip a new Turnstile challenge for that short window.

This behavior is configurable in Back Office:

* Cookie validity is set in seconds, common value is 600 seconds (10 minutes)&#x20;
* When disabled, the server does not issue this cookie and Turnstile verification is required for each submission path.

#### Legal requirement: security cookie

This cookie should be listed in the cookie policy (often under “strictly necessary” / “security cookies”).

* Cookie name: `neo.<tenantId>.turnstile-proof` where `<tenantId>` is the identifier of your wallet crew tenant
* Purpose: Keep bot-protection state between requests and avoid repeated Turnstile challenges
* Category: Security cookie (generally considered strictly necessary)
* Lifetime: Configurable (seconds). Set to 0 to disable.
* Scope: Enrolment form submission
* Technical attributes:
  * `HttpOnly`
  * `Secure`
  * `SameSite=Lax`
  * `Path=/`

This cookie is used only for security and fraud prevention, not for analytics or marketing.

## FAQ

<details>

<summary>Does Turnstile always show a CAPTCHA-like challenge?</summary>

No. Turnstile often completes in the background. An interactive widget is only displayed when Cloudflare requires extra verification.

</details>

<details>

<summary>Is Turnstile enough to fully block bots?</summary>

No. Turnstile provides baseline bot mitigation, but it is not perfect. Modern abuse can use AI-assisted automation, proxy networks, and human-in-the-loop solving.

Cloudflare’s official documentation covers Turnstile’s intent and behavior: [Cloudflare Turnstile docs](https://developers.cloudflare.com/turnstile/).

</details>

<details>

<summary>Which keys are needed from Cloudflare?</summary>

The Wallet Crew requires the Turnstile widget **Site key** and **Secret key**.

Cloudflare explains how to create a widget and retrieve those values here: [Turnstile “Get started”](https://developers.cloudflare.com/turnstile/get-started/).

</details>

<details>

<summary>What happens if the Turnstile token is missing or invalid?</summary>

When the extension is enabled, the enrolment submission is only accepted when a valid Turnstile token is received and successfully verified server-side. Invalid, expired, or missing tokens are treated as non-legitimate submissions.

</details>

<details>

<summary>How to test that Turnstile is correctly configured?</summary>

A quick validation is to submit the enrolment form from a normal browser session and confirm it completes without friction. A second validation is to open the same flow in a stricter context (private browsing, disabled third-party cookies, VPN, or automation tooling) and confirm Turnstile still behaves as expected.

Cloudflare documents recommended test patterns and integration steps in the setup guide: [Turnstile “Get started”](https://developers.cloudflare.com/turnstile/get-started/).

</details>

<details>

<summary>Which domain should be configured on the Cloudflare widget?</summary>

Add the **custom domain** that hosts the enrolment form.

This is configured in the Turnstile widget settings in Cloudflare. Cloudflare’s setup guide covers widget configuration details: [Turnstile “Get started”](https://developers.cloudflare.com/turnstile/get-started/).

</details>