Cloudflare Turnstile: how it works and how to solve it (coming soon)
Cloudflare Turnstile is a captcha that usually asks nothing of the visitor. It runs checks in the browser, and in most cases it passes without any puzzle. When it is not sure, it may show a short interactive step. The widget then writes a token into the form, and the site verifies that token with Cloudflare. Scarnox support for Turnstile is coming soon. This guide explains how the widget works, why it is often confused with other challenges, and the general approaches for legitimate work.
How the widget is embedded
The page includes a container element with the cf-turnstile class and a data-sitekey attribute. The Turnstile script loads, runs its checks, and adds a hidden input named cf-turnstile-response. The value of that input is the token. The form submits it with the rest of the fields, and the site's backend sends it to Cloudflare's verification endpoint together with the site's secret key.
Like other token widgets, the verification happens on the server. A form that accepts any value in that field without checking it is not really protected.
Modes and what they mean for a script
Turnstile can run in more than one mode. In the managed mode, Cloudflare decides whether to show an interactive step. In the non-interactive mode, the widget never asks the visitor for anything and just shows a status. In the invisible mode, nothing is shown at all. For a script, the mode changes what you will see on the page, but the outcome is the same: a token in the form field, verified on the server.
Tokens are short-lived and single use. Submit the form soon after the widget produces the token, and do not reuse a token that has already been verified.
Why it blocks automation
Turnstile looks at signals from the browser environment and at the behaviour of the session. A default headless browser, a missing or inconsistent set of browser features, a fresh session with no history and a suspicious network address can all push the decision towards a challenge or a block. The signals are the same family as those used by other score-based checks, which is why the approaches are similar.
Legitimate approaches
These are the approaches that work for legitimate work:
- Use a real browser for pages that load Turnstile. A normal browser profile with consistent settings is less likely to be challenged than a bare automation build. The headless browser detection guide lists the common signals.
- Stay in the session. Keep cookies across the pages of your workflow, so the visitor does not appear new on every request.
- Pace your requests. A steady, human-like rate reduces challenges far more than any single trick.
- Read the Cloudflare-protected site's rules first. Many protected sites publish an API or a feed. Check that before building a browser workflow. The scraping Cloudflare-protected sites guide covers the approach in more depth.
- Use test keys in development. Cloudflare publishes test site keys for development, which produce predictable results without a real check. They are for your own integration tests, not production traffic.
- Ask the owner. If you run the site, you can adjust the Turnstile settings for the paths your automated tests use. If you do not, ask for an allowlist or an API.
What a Turnstile solver will do
A token-based Turnstile solver takes the sitekey and page URL, produces a valid token for the cf-turnstile-response field, and returns it to your code. Your code writes the token into the form and submits it promptly. This is the same pattern as the live PopularCaptcha integration, with a different task type.
Scarnox does not solve Turnstile live yet. The only live task type today is PopularCaptcha, proxyless. Turnstile is coming soon, and its request details will be in the API reference when it ships. Do not build against an assumed interface before then.
Common mistakes
Turnstile integrations tend to fail in a few predictable ways. The most common is using a token after it has expired or after it has already been verified. Tokens are single use, so a retry after a failed form submission needs a fresh widget result, not the old value. The second is a sitekey that belongs to a different environment. A development key on a production page, or the reverse, produces a verification failure that looks like a bug in your code. Check which key the page is using before you debug anything else.
Another frequent mistake is treating an interactive step as a failure. In managed mode, Turnstile may show a short step to some visitors, and a script that expects a silent pass will stall on it. Build the flow to wait for the widget's result, and to handle the case where the widget asks for more.
Finally, do not hard-code the field name without checking it on the live page. The cf-turnstile-response input is the standard, but a site can wrap the widget differently, and reading the rendered form is faster than guessing.
Scrape responsibly
Scraping a site protected by Turnstile is a common job, and it needs the same care as any other scraping. Check robots.txt and the terms of service. Keep your rate low, and do not collect personal data you do not need. Where a site has an API, prefer it. The is web scraping legal guide covers the main questions.
Getting ready
Create an account to start with free trial credit, no card needed. When Turnstile support ships, you will be able to test it on your own pages before you run anything against a live site.