What Is Cloudflare Turnstile? The CAPTCHA Widget Explained

Cloudflare Turnstile is a CAPTCHA replacement: a small widget a website puts on a form, such as a login or sign-up page, to tell people from scripts without asking anyone to click pictures. If you build automation, tests or data pipelines against a site that uses it, you meet it as a box that has to produce a token before the form is accepted. This guide explains what happens inside that box, so the rest of the work makes sense.

The short version

1. The site embeds the Turnstile script and a widget configured with its sitekey.
2. In the visitor’s browser, the widget runs a set of checks. Most visitors never see a question: the checks finish in the background, and some widgets are fully invisible.
3. When the checks pass, the widget produces a token and places it in the form, in a hidden field named cf-turnstile-response, or hands it to a JavaScript callback.
4. The form is submitted. The site’s server sends the token to Cloudflare’s siteverify endpoint with its secret key, and Cloudflare answers whether the token is valid.
5. Only then does the site accept the login, the sign-up or whatever the form was for.

The token is the part that matters to automation. It is single-use, and it expires 300 seconds after it is issued. See Cloudflare Turnstile token expiry for what that means in practice.

The parts of a widget

Part	Where it lives	What it does
Sitekey	In the page, public	Identifies the widget. Starts with 0x4AAAAAAA for most widgets.
Secret key	On the site’s server, private	Lets the server verify tokens. Never in the page.
Action	In the page, optional	A label such as login, returned when the token is verified.
cData	In the page, optional	Customer data the site attaches, also returned on verification.
Mode	In the Cloudflare dashboard	Managed, non-interactive or invisible.

The sitekey is what you need to automate the page. Find a Cloudflare Turnstile sitekey shows where it appears in the HTML. Action and cData are covered in Cloudflare Turnstile action and cData, and the modes in Cloudflare Turnstile widget modes.

How verification works on the site’s side

The server-side check is a single HTTPS call. The site posts the token and its secret key to https://challenges.cloudflare.com/turnstile/v0/siteverify, optionally with the visitor’s IP address and an idempotency key. The answer says whether the token is valid and, if it is not, why, with error codes such as timeout-or-duplicate for a token that expired or was already used, or invalid-input-response for one that is malformed.

Two consequences follow. First, a token only proves something at the moment it is verified: a token that sat in a queue for six minutes fails. Second, a token can be redeemed once: submitting the same token to two forms fails the second time. Cloudflare’s own Cloudflare Turnstile documentation covers the server call in full.

Where you meet Cloudflare Turnstile

• Login and sign-up forms, where it slows down credential stuffing and fake accounts.
• Checkout and contact forms, where it filters spam.
• Search and listing pages on some sites, before results load.
• Your own sites, if your team adds Turnstile and needs end-to-end tests that pass it. For that case you do not need a solver at all: Cloudflare publishes testing sitekeys, covered in Test Cloudflare Turnstile in CI.

What this means for automation

A headless browser or an HTTP client cannot produce a Turnstile token by itself. The practical options are:

1. Cloudflare’s testing sitekeys on your own site, when you control the site.
2. An allowlist that the site owner configures for your traffic.
3. A solving API, which takes the page URL and sitekey and returns a token that your code submits the way the page would.

The third option is what ZeroCaptcha does. You send a task with websiteURL and websiteKey, you get a task ID back at once, and you poll until the token is ready, or receive it by callback. The Cloudflare Turnstile solver page shows the whole flow, and the quickstart has a complete program in Python, Node, Go and curl.

Use it only on sites you are allowed to automate: your own, a client’s with permission, or pages whose terms allow it. The Acceptable Use Policy spells out the rules.

Words worth knowing

• Token: the string the widget produces and the site verifies. One use, 300 seconds.
• Siteverify: Cloudflare’s endpoint that checks a token for the site’s server.
• Challenge: the checks the widget runs, visible or not.
• Challenge page: a different Cloudflare feature, a full-page interstitial that sets a cf_clearance cookie. See Cloudflare challenge page vs Cloudflare Turnstile.

The glossary defines these and the other terms you will meet in the API.