What is Cloudflare Turnstile? How it works, and what the integration looks like

Cross-posted from blog.peak.fo. I work on Peak, the solving API mentioned at the end.

Cloudflare Turnstile is a CAPTCHA replacement that decides whether a visitor is human by watching how their browser behaves, instead of making them label images. Most visitors see nothing more than a checkbox that ticks itself. Behind that checkbox, Cloudflare runs a set of browser checks and issues a token the site uses to confirm the visit is legitimate.

Below: what it checks, the three modes, what the integration looks like from the site's side, and why so many sites switched to it.

How Turnstile works

When a page loads Turnstile, a small script runs in the visitor's browser. It looks at signals the browser gives off: the JavaScript environment, how rendering behaves, and subtle traits that separate a real browser from a headless script. Cloudflare pairs that with its own reputation data for the visitor's IP, since it sits in front of a large chunk of the web and has seen that address before.

If the checks pass, Turnstile writes a token into a hidden field called cf-turnstile-response. The site sends that token to its server, the server asks Cloudflare to verify it, and the visit proceeds. No puzzle, no images, usually no interruption. When Cloudflare is less sure, it may show an actual checkbox to click, but the heavy lifting is invisible.

The three modes

Turnstile comes in three flavors, and the difference is how visible it is:

• Non-interactive: runs silently, no click. The common case.
• Managed: Cloudflare decides in the moment whether to show a checkbox, based on how risky the visit looks.
• Invisible: no widget renders at all. The check happens in the background.

All three end the same way: a token that proves the check ran. The mode only changes whether the visitor notices.

What it looks like on the page

From the site owner's side, there are two pieces. First, the client script and a widget element carrying the public sitekey:

<script src="https://challenges.cloudflare.com/turnstile/v0/api.js" async defer></script>

<form method="POST" action="/login">
  <div class="cf-turnstile" data-sitekey="0x4AAAAAAAxxxxxxxxxxxx"></div>
  <button type="submit">Log in</button>
</form>

When the widget finishes, it adds the cf-turnstile-response field to the form, so the token rides along with the POST. Second, the server sends that token to Cloudflare's siteverify endpoint together with the site's secret key:

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

The JSON that comes back has "success": true or an error code. Two details from Cloudflare's docs matter later if you automate against it: a token expires after 300 seconds, and each token can be validated only once. A replayed token is rejected.

The sitekey is public and sits in the page source. The secret key stays on the server, which is why a token can't be forged by someone who only has the page.

Why sites use it

Two reasons carry most of the switch. It's free with unlimited challenges, which is not true of reCAPTCHA Enterprise or hCaptcha's paid tiers. And it doesn't hand visitor data to an advertising network, which matters for privacy and for the regulations around it. Add that most people never have to solve anything, and you get fewer abandoned forms. It also doesn't require the site to route its traffic through Cloudflare: you need a Cloudflare account to get keys, and you can drop the widget into any page.

What Turnstile is not

It isn't a wall. Turnstile raises the cost of automated abuse; it doesn't make it impossible. The token is only as trustworthy as the browser and IP behind it, which is why, on the automation side, solving Turnstile comes down to presenting a clean environment and a good IP rather than defeating a puzzle.

If you're doing legitimate automation, scraping public data, or testing your own forms, see how to solve Cloudflare Turnstile for the practical version. Curious how it compares with the alternatives? We wrote up Turnstile, reCAPTCHA, and hCaptcha side by side.

If you'd rather not run the browser side yourself, Peak's API takes the sitekey and page URL and returns a token you put in the cf-turnstile-response field:

import requests

resp = requests.post(
    "https://api.peak.fo/solve",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "task_type": "turnstiletask",
        "url": "https://target.com/",
        "sitekey": "0x4AAAAAAAxxxxxxxxxxxx",
    },
    timeout=60,
)
token = resp.json()["data"]["token"]

Pricing is $0.90 per 1,000 successful solves, dropping to $0.35 at the largest package, and failed solves aren't billed. New accounts get 1,000 free solves to test with. Parameter reference is in the Peak docs.

FAQ

What is Cloudflare Turnstile in simple terms?

It's a CAPTCHA that checks your browser in the background and gives the site a token proving you're likely human, instead of asking you to solve a puzzle. Most visitors just see a checkbox that completes on its own.

Is Cloudflare Turnstile free?

Yes, it's free for site owners with unlimited challenges, which is a big part of why it's grown so fast against paid options.

Does Turnstile track users?

Turnstile is built to collect minimal data and doesn't feed a third-party ad network, which is one of its main selling points over reCAPTCHA.

How long does a Turnstile token last?

300 seconds, and it can be verified once. After that you need a fresh token.

Working with Turnstile in your own automation? Start free at peak.fo.