What Is Cloudflare Turnstile? Modes, Token and Verification

What is Cloudflare Turnstile? It is a CAPTCHA alternative from Cloudflare. It checks a visitor with tests that run in the background instead of picture puzzles, and when the visitor passes, the page receives a token that the site’s server then verifies with Cloudflare. This guide covers the three widget modes, the token and its limits, how verification works, and how to tell the widget from the full-page challenge.
What the visitor sees: three widget modes
Cloudflare describes three modes in its widget documentation. The site owner picks one when creating the widget.
| Mode | What the visitor sees |
|---|---|
| Managed mode | Cloudflare chooses between a non-interactive check and a checkbox, so a checkbox shows only when a further check is needed |
| Non-interactive mode | A widget with a loading spinner while the checks run, and the visitor is never asked to do anything |
| Invisible mode | Nothing at all: no widget and no spinner, and the checks run in the background |
None of the three asks the visitor to read distorted text or pick pictures. A site does not have to route its traffic through Cloudflare to use the widget, according to the Cloudflare overview, but its owner does need a Cloudflare account to create one.
What does Cloudflare Turnstile give the page? A token
For a developer it comes down to a form field called cf-turnstile-response, a verification call on the server and, when you automate a site that uses it, a token you have to supply yourself. When the widget sits inside a form, Cloudflare says it adds an invisible input named cf-turnstile-response, which travels to the server with the other fields. The widget can be rendered implicitly, where it scans the markup for an element with the cf-turnstile class, or explicitly with a call to turnstile.render() from the page script. A page that renders explicitly can also pass a callback, and the CapSkip API docs say to run that callback with the returned token if the page defines one.
The token is short-lived. The server-side validation guide says each token is valid for 300 seconds and intended for single use, and that Cloudflare tracks redemption across its network with a delay. So a token you request at the top of a long script may be spent or stale by the time the form goes out.
How the server verifies the token
Receiving the field proves nothing by itself. Cloudflare calls server-side validation mandatory: the site sends the token and its secret key to the siteverify endpoint, a POST to https://challenges.cloudflare.com/turnstile/v0/siteverify, and reads a JSON answer. The documented values are below.
| Direction | Value | Meaning |
|---|---|---|
| Sent | secret (required) | The secret key of the widget |
| Sent | response (required) | The token from the form field |
| Sent | remoteip (optional) | The visitor’s IP address |
| Sent | idempotency_key (optional) | A UUID you generate so that a retry of the same check is safe |
| Returned | success | Whether the validation passed |
| Returned | challenge_ts, hostname | When the challenge was solved and where it was served |
| Returned | error-codes | A list such as missing-input-response or timeout-or-duplicate |
| Returned | action, cdata | Custom values that the page set on the widget |
Cloudflare lists seven error codes, and two matter here. The code missing-input-response means no token reached Cloudflare, and timeout-or-duplicate means the token expired or was already validated. The documented answer carries no score: the result is a pass or a fail, with the action and cdata values your page set so the server can check them. This is a reading of the documented fields, not a statement from Cloudflare about what it never returns.
Widget or challenge page: which Turnstile is this?
The widget is one thing and the full-page challenge is another. The widget is an element in a page that already loaded. A challenge page is what Cloudflare shows instead of the site, before any content arrives. The clearance documentation from Cloudflare says solving such a challenge sets a cf_clearance cookie that is tied to the visitor and device. It also says a widget with pre-clearance enabled can issue that cookie, whereas by default the widget issues a one-time token. Use this table to decide what you are looking at.
| What you see | What it is | What CapSkip needs from you |
|---|---|---|
| A box or spinner inside a form, and a cf-turnstile-response input in the HTML | The widget, in managed or non-interactive mode | The sitekey and the full page address. The token goes into the field |
| A form that fails without the token, but no box on screen | The widget in invisible mode, or one that did not render | The same two values. Find the sitekey in the markup or in the render call |
| A full page that reads "Just a moment" before the site loads | The full-page challenge | Two CapSkip routes. A Turnstile token request carrying action, data and pagedata when the page passes them to turnstile.render, or the cf_clearance cookie request described below |
Getting a Turnstile token from CapSkip
CapSkip runs on your own Windows PC and answers on 127.0.0.1:8080 in the 2captcha request format, with no per-solve fee on a licensed copy. The Cloudflare Turnstile solver page describes the product, and the API docs list the parameters used here. If your script runs on another machine, switch CapSkip to Server mode and use that PC’s address as the host, as the connection settings section of the setup guide explains. CapSkip opens its port to every address when Server mode starts, so to keep it to the machines you expect, add a Windows Firewall block rule for the others.
Here is the widget request by hand. The method is turnstile, and the API docs list sitekey and pageurl as the required values. Each call is one line of curl.exe, which PowerShell runs as written. In cmd, leave out the lines that start with a hash.
# 1. Submit the task. CapSkip answers with a task id.
curl.exe -s -X POST -d "key=YOUR_API_KEY&method=turnstile&sitekey=YOUR_SITEKEY&pageurl=https://example.com/contact&json=1" http://127.0.0.1:8080/in.php
# {"status":1,"request":"12345"}
# 2. Poll with that id until the token is ready.
curl.exe -s "http://127.0.0.1:8080/res.php?key=YOUR_API_KEY&action=get&id=12345&json=1"
# {"status":0,"request":"CAPCHA_NOT_READY"} means poll again shortly.
# {"status":1,"request":"TOKEN","userAgent":"Mozilla/5.0 ..."}The same task through the Python SDK is one call. It submits, polls and returns a dictionary whose code value is the token for the cf-turnstile-response field.
# python -m pip install capskip
from capskip import CapSkip
# Local mode. In Server mode, use your server's address as the host.
solver = CapSkip(host="127.0.0.1", port=8080)
result = solver.turnstile("YOUR_SITEKEY", "https://example.com/contact")
print(result["code"]) # the token for the cf-turnstile-response field
print(result.get("userAgent")) # the User-Agent to send with itThe API docs say CapSkip solves Turnstile with a specific browser User-Agent and that you must send the same one when you submit the token. With the JSON reply the answer carries it as userAgent, and in plain text mode it comes in the X-Turnstile-User-Agent response header. The SDK asks for the JSON reply, so read the value from the result and put it on the request that carries the token.
The challenge page request
For a challenge page the API docs ask you to pass three more values, which you read from the arguments the page gives turnstile.render(). Send the ones the page defines, and do not send empty ones. The docs include a short script that overrides that function and prints the arguments.
| Request value | Where the page keeps it |
|---|---|
| action | The data-action attribute, or the action in the render call |
| data | The cData value in the render call, or the data-cdata attribute |
| pagedata | The chlPageData value in the render call |
# python -m pip install capskip
from capskip import CapSkip
solver = CapSkip(host="127.0.0.1", port=8080)
# action, data and pagedata come from the page's turnstile.render call.
result = solver.turnstile(
"YOUR_SITEKEY",
"https://example.com/protected",
action="managed",
data="YOUR_CDATA",
pagedata="YOUR_CHLPAGEDATA",
)
print(result["code"], result.get("userAgent"))The managed value for action is copied from the sample request in the API docs, so use whatever action your page defines.
The cookie route is a different request. The API docs list it under Cloudflare Challenge (cf_clearance), for the full page that reads "Just a moment". It works only through the JSON createTask API, it is off until you turn on Return cf_clearance cookies under the Cloudflare settings, and every request must name the proxy you will use afterwards. The Python SDK has no call for it, so here is the request in the shape the API docs write it, sent with PowerShell. The proxy value is the placeholder from the docs.
# Submit the cookie task. A proxy is required.
$body = '{"clientKey":"YOUR_API_KEY","task":{"type":"AntiCloudflareTask","websiteURL":"https://www.example.com/","proxy":"203.0.113.10:8080:login:password"}}'
$task = Invoke-RestMethod -Method Post -Uri http://127.0.0.1:8080/createTask -ContentType "application/json" -Body $body
# Poll every few seconds while the status is processing.
$ask = @{ clientKey = "YOUR_API_KEY"; taskId = $task.taskId } | ConvertTo-Json
do {
Start-Sleep -Seconds 5
$result = Invoke-RestMethod -Method Post -Uri http://127.0.0.1:8080/getTaskResult -ContentType "application/json" -Body $ask
} while ($result.status -eq "processing")
$result.solution.cookies.cf_clearance
$result.solution.userAgentUse the cookie request when you want to fetch the site with ordinary HTTP requests after the challenge. The API docs describe that case for a script or tool with no browser of its own, and say to send the cookie through the same proxy and with the same User-Agent. The token request fits a page that calls turnstile.render() and has a callback or a field that takes the token. That pairing for the token request is an inference from the two sections of the docs, not a statement from them.
For reusing the cookie in Python, see how to reuse cf_clearance cookies. For the token request in code, see the Node.js guide. The PHP version is in solving Turnstile in PHP, and the C# version is in the C# challenge page guide.
What I ran, and what it does not show
I ran all four code blocks against a mock that plays CapSkip, on Python 3.11.7, 3.13.7 and 3.14.0 with capskip 1.7.0, and the two PowerShell blocks in Windows PowerShell 5.1. I sent no task to the real app, so nothing here shows how a real Turnstile page responds or what the real app returns for a widget.
| Check against the mock | Result |
|---|---|
| Python widget call | One task with method turnstile, the sitekey and the page address, and the token and User-Agent came back in the result |
| Python challenge page call | The same task also carried action, data and pagedata, exactly as passed |
| Both Python blocks pasted into one file | Both tasks were sent and read back |
| Cookie route in PowerShell | The mock saw type AntiCloudflareTask, the page address and the proxy. It answered processing once, then the cookie and the User-Agent, which the block printed |
| curl.exe submit, then poll | The first poll said the task was not ready and the second returned the token |
FAQ
How long does a Turnstile token last?
Cloudflare says 300 seconds, and tokens are intended for single use. Request the token from CapSkip just before the form goes out.
Is Turnstile the same as the Cloudflare check before a site loads?
No. The widget lives inside a page and yields a token. The full-page challenge replaces the page and ends in a cf_clearance cookie. The decision table above shows how to tell them apart.
Can I see a Turnstile widget before I write any code?
Yes. Open the Turnstile demo page to see a live widget and the field it fills in.
Can I call the solver from another PC?
Yes, through Server mode. Use the address of the PC that runs CapSkip as the host and add a Windows Firewall block rule for any address that should not reach it. The solver still runs on your own Windows hardware.
The short version
In short, what is Cloudflare Turnstile? A token in cf-turnstile-response that the site checks with Cloudflare, next to a separate full-page challenge that ends in a cookie. To supply the token or cookie from your own code, a local captcha bypass tool such as CapSkip does it on your own PC, with a flat license and no per-solve fee.
