Cloudflare Turnstile setup guide

What Turnstile is

Cloudflare Turnstile is a CAPTCHA alternative that verifies a visitor without showing a visible image puzzle. It runs a short, per-request JavaScript challenge that gathers signals about the browser, then returns a signed token the site can validate. It aims to let a human through with almost no interaction while making automation hard.

Two properties distinguish it from older CAPTCHAs: there is no image grid to solve, and it does not store cookies about the visitor. This makes it lighter to use on forms while still gating submissions.

Widget markup

Create a Turnstile site in your Cloudflare dashboard to get a site key and a secret key. Add the widget to a page by loading the script and placing a container:

<script src="https://challenges.cloudflare.com/turnstile/v0/api.js" async defer></script>
<div class="cf-turnstile" data-sitekey="YOUR_SITE_KEY"></div>

The widget fills the container and, on interaction, writes the token into a hidden field named cf-turnstile-response. When you submit a form, include that token with the rest of the payload.

Turnstile relies on the widget completing, so place it inside your form and let it render before the user submits. Do not treat the client-side widget alone as protection; the real gate is server-side validation.

Validate server-side

Client-side-only Turnstile is decoration. An attacker can skip the form UI entirely, so you must verify the token on the server before trusting the submission. Send a POST to the siteverify endpoint with the site secret and the token:

curl -X POST https://challenges.cloudflare.com/turnstile/v0/siteverify \
  -d "secret=YOUR_SECRET_KEY" \
  -d "response=TOKEN_FROM_THE_FORM"

A JSON response with "success": true means the token was valid and unused. Anything else, including "success": false, should reject the submission. Calls after first-time use and retries with an idempotency key are supported so a flaky network does not double-consume a token.

Practical checklist:

• Keep the secret key server-side, never in page source.
• Validate the token on every submission, not only suspicious ones.
• Treat a failed check exactly like a blank form field and show a clear error.
• Combine Turnstile with custom WAF rules and rate limiting so challenge, allowlist and volume protections cover different attack angles.

Understand how Cloudflare decides the security level for the rest of your traffic, and the Turnstile verdict stays consistent with the wider bot posture rather than a one-off check.