Turnstile is Cloudflare's CAPTCHA replacement: the service checks a visitor without pictures, traffic lights, or picking the right tiles in a photo.
How Turnstile differs from a regular CAPTCHA
The difference is not only the lack of pictures but the whole checking principle: a classic CAPTCHA checks a human through a puzzle, Turnstile checks through browser and device behavior signals.
| Criterion | Regular CAPTCHA | Turnstile |
|---|---|---|
| What the visitor sees | pictures, a puzzle, or a checkbox | usually just a short check with no tasks |
| What is checked | the ability to recognize an object in a picture | browser and device signals, no puzzle |
| Is a Cloudflare account needed | no, it is a third-party service | yes, the widget is issued in the Cloudflare dashboard |
| Does it work outside a Cloudflare proxy | yes, it does not depend on a proxy | yes, it works even without proxying the site through Cloudflare |
How it works in general terms
The widget on the page checks the visitor in the browser and issues a token confirming the result of the check. That token goes into the form along with the other fields, and before processing the form the server sends the token off for verification and gets back whether it was confirmed or not.
Where Turnstile is usually placed
- A sign-in form for an account.
- A registration form for a new user.
- A contact form on a site.
- A comment form under an article.
How to add the widget and verify the token
Setting it up takes two steps: widget markup on the page and token verification on the server.
<div class="cf-turnstile" data-sitekey="your-site-key"></div>The second step is server-side verification before processing the form: the token value from the hidden form field is sent along with the secret key for verification, and the form is processed only when the result is confirmed.
# take the token from the submitted form
# send the token together with the secret key for verification
# continue processing the form only if verification is confirmedCommon connection mistakes
| Problem | Likely cause | What to do |
|---|---|---|
| The widget does not appear on the page | the site key is wrong or the widget script is not loaded | check the key and the widget script connection |
| The token fails server verification | the secret key is mixed up with the site key | check which key is used on the server and which in the markup |
| The widget breaks on mobile | the parent form block is too narrow or clipped by styles | check the block width and horizontal overflow |
| The check triggers on your own visitors | a stale or already used token was submitted again | refresh the token on every form resubmission |
What Turnstile does not solve
Turnstile checks the visitor filling out a form, but it does not protect against server overload from a flood of requests and does not limit request frequency. For spam protection in general, see the article on protecting a site from spam, and for limiting request frequency and password guessing, see the article on protection against brute-force attacks.
Short conclusion
Turnstile is worth adding where a form is filled out by a real person and it matters to cut off automated submissions without extra steps for the visitor. Where the problem is request volume rather than its source, the widget alone is not enough, and request-rate limiting is needed.