Skip to main content

CAPTCHA guide

Cloudflare Turnstile & Challenge

Turnstile widget and full-page edge challenge, judged mostly on browser and network reputation.

Difficulty: Medium – Very high
Risk engine
Exploded concept drawing of how the Cloudflare Turnstile challenge is built

Cloudflare sits in front of tens of millions of websites, more than any other infrastructure and security provider. Before tackling it, separate its two defences: Cloudflare Turnstile, a smart CAPTCHA widget that sites embed in their pages, and Cloudflare Challenge / Bot Management, a full-page barrier enforced by the WAF at the network edge.


Turnstile vs. edge challengeLink to Turnstile vs. edge challenge

Feature Cloudflare Turnstile (widget) Cloudflare edge challenge / Bot Management
What it is An embeddable CAPTCHA replacement An anti-bot interstitial page served by the WAF/CDN
What triggers it Placed in forms (login, sign-up, checkout) WAF rules, IP threat score, Bot Fight Mode
What the visitor sees Either nothing (auto-solve) or a checkbox "Just a moment...", "Checking your browser", a full reload
What it produces A signed token in cf-turnstile-response A cf_clearance cookie, plus __cf_bm session cookies
Lifetime 300 seconds (5 minutes), single-use Varies, typically 30 minutes to 24 hours per IP and User-Agent
Server check The backend calls challenges.cloudflare.com/turnstile/v0/siteverify Checked automatically by Cloudflare's edge proxy
Complexity 3/5 (Medium) 5/5 (Very High)

Architecture under the hoodLink to Architecture under the hood

1. How Turnstile worksLink to 1. How Turnstile works

Turnstile was built as a privacy-first alternative to reCAPTCHA. It drops visual puzzles in favour of machine-learning heuristics and cryptographic proofs.

  • Client script: loaded from https://challenges.cloudflare.com/turnstile/v0/api.js.
  • Sandboxed iframe: everything runs in an isolated cross-origin iframe (challenges.cloudflare.com/cdn-cgi/challenge-platform/h/b/turnstile/...).
  • Signals it evaluates:
    • Proof-of-work (PoW): the browser solves changing cryptographic puzzles (SHA-256 or custom hashing).
    • Private Access Tokens (PAT) / Privacy Pass: on supported platforms (macOS, iOS, Android), cryptographic tokens vouch for genuine hardware without tracking.
    • CDP and automation detection: it looks for DevTools hooks, Runtime.enable traces, modified prototypes, navigator.webdriver and odd execution timing.
    • Interactive check: when risk looks high, it falls back to a "Verify you are human" checkbox.
  • Token hand-off: on success, a signed base64 payload is written to a hidden <input type="hidden" name="cf-turnstile-response" id="cf-turnstile-response">.

The round trip, step by step:

  1. The browser loads the Turnstile widget script.
  2. The widget runs the PoW, collects telemetry and checks for a PAT.
  3. The resulting token lands in cf-turnstile-response and is submitted with the form.
  4. The site's server posts it to /turnstile/v0/siteverify, and Cloudflare's API answers with JSON.

2. How the edge challenge and Bot Management workLink to 2. How the edge challenge and Bot Management work

Bot Management inspects traffic at layers 3, 4 and 7, before it ever reaches the customer's origin server.

  • Detection layers:
    • TLS fingerprinting (JA3 / JA4 / Akamai fingerprint): compares cipher suites, extensions, elliptic curves and TCP/IP window sizes to tell real browsers from HTTP libraries such as Python requests, aiohttp or Go-http-client.
    • HTTP/2 and HTTP/3 frame signatures: checks SETTINGS values, WINDOW_UPDATE frames and the order of pseudo-headers (:method, :authority, :scheme, :path).
    • Behavioural ML engine: weighs request rate, the reputation of the IP's ASN, request sequences and anomalies seen across Cloudflare's whole network.
  • How a challenge escalates:
    1. HTTP 403 / 503: the edge stops the request and serves the interstitial with a cf-mitigated: challenge header.
    2. JavaScript orchestration: /cdn-cgi/challenge-platform/h/b/orchestrate/chl_page/v1 loads and runs in-depth environment checks.
    3. Clearance: a successful check sets cf_clearance, bound tightly to the client's IP address + User-Agent + TLS fingerprint.

Product detailsLink to Product details

1. Cloudflare TurnstileLink to 1. Cloudflare Turnstile

Identifying it in the DOMLink to Identifying it in the DOM

  • Script: <script src="https://challenges.cloudflare.com/turnstile/v0/api.js" async defer></script>
  • Container: <div class="cf-turnstile" data-sitekey="0x4AAAAAA..." data-callback="onTurnstileSuccess"></div>
  • Hidden field: <input type="hidden" name="cf-turnstile-response" value="...">
  • Iframe selector: iframe[src*="challenges.cloudflare.com"], with an id starting cf-chl-widget-
  • Global JS API: turnstile.render(), turnstile.reset(), turnstile.getResponse(), turnstile.execute()

Widget modesLink to Widget modes

  1. Managed: Cloudflare runs its checks in the background and only shows a checkbox when the signals are borderline.
  2. Non-interactive: runs on its own with no click, showing a spinner and then a tick.
  3. Invisible: nothing is drawn in the DOM; the site triggers it from JavaScript with turnstile.execute().

2. Cloudflare edge challenge (JS, Managed and Under Attack Mode)Link to 2. Cloudflare edge challenge (JS, Managed and Under Attack Mode)

How it looksLink to How it looks

  • A full-page interstitial: "Just a moment... Enable JavaScript and cookies to continue".
  • The Cloudflare Ray ID and the protected domain are displayed.
  • An interactive verification box may be embedded.

Identifying it on the networkLink to Identifying it on the network

  • Status code 403 Forbidden or 503 Service Temporarily Unavailable.
  • Response headers:
    • server: cloudflare
    • cf-mitigated: challenge
    • cf-ray: 8e1...
  • Cookies to know:
    • cf_clearance: the main authorisation cookie that lets later requests through the edge.
    • __cf_bm: the Bot Management tracking cookie, valid for 30 minutes.
    • cf_chl_*: short-lived cookies that hold the challenge state.

Official test keys and test environmentsLink to Official test keys and test environments

Cloudflare dummy keysLink to Cloudflare dummy keys

Cloudflare publishes test keys for integration work. They work on any domain, localhost and 127.0.0.1 included.

Client-side dummy sitekeysLink to Client-side dummy sitekeys

Sitekey Behaviour Widget mode Use it to
1x00000000000000000000AA Always passes Visible Test a successful form submission
2x00000000000000000000AB Always fails Visible Test client-side error handling and retries
1x00000000000000000000BB Always passes Invisible Test invisible execution
2x00000000000000000000BB Always fails Invisible Test invisible failure handling
3x00000000000000000000FF Forces an interactive challenge Visible Test the manual checkbox flow

Server-side dummy secret keysLink to Server-side dummy secret keys

Secret key Validation result Error code
1x0000000000000000000000000000000AA {"success": true} None
2x0000000000000000000000000000000AA {"success": false} invalid-input-response
3x0000000000000000000000000000000AA {"success": false} timeout-or-duplicate

Live test and benchmark environmentsLink to Live test and benchmark environments

Environment URL Type What it offers
Cloudflare Turnstile docs developers.cloudflare.com/turnstile Turnstile Product docs, widget modes, siteverify
Official dummy-key matrix testing Turnstile Keys that predictably pass, fail or go interactive
Peet Turnstile demo peet.it/turnstile Turnstile A tidy community demo covering several widget modes
ZeroCDN Turnstile lab turnstile.zerocdn.com Turnstile A public test bed for pulling tokens out
NowSecure challenge lab nowsecure.nl WAF challenge The classic domain for testing the edge Managed Challenge
ScrapingCourse Turnstile scrapingcourse.com/cloudflare-turnstile Turnstile A scraping practice site

Bypass methods and engineering approachesLink to Bypass methods and engineering approaches

Method 1: anti-CDP browser automation (Turnstile and interactive WAF)Link to Method 1: anti-CDP browser automation (Turnstile and interactive WAF)

Stock Playwright and Puppeteer leak Chrome DevTools Protocol traces (Runtime.enable, Page.addScriptToEvaluateOnNewDocument), and Cloudflare spots them at once.

  • What to use instead: automation frameworks patched to remove those traces:
    • rebrowser-patches: patches the Playwright and Puppeteer source so CDP runs in isolated execution contexts.
    • SeleniumBase UC Mode (sb.uc_gui_click_cf()): reconnects through PyAutoGUI/CDP and clicks the Turnstile box with real OS-level mouse events.
    • Camoufox: a Firefox engine patched in C++ to resist fingerprinting and canvas/WebGL probes.
    • nodriver: an async Python CDP client that needs no WebDriver binary.

Method 2: harvest the clearance once, then impersonate TLS (edge challenges)Link to Method 2: harvest the clearance once, then impersonate TLS (edge challenges)

On high-volume endpoints behind the Cloudflare WAF, starting a browser for every request costs far too much. The usual pattern:

  1. An anti-detect browser (Camoufox or UC Mode) solves the Managed Challenge once.
  2. You extract cf_clearance, the other cookies and the exact User-Agent.
  3. A TLS-impersonating client (curl_cffi, tls-client or rhttp, in Python or Go) carries on at high speed over HTTP/2, with a matching JA3/JA4 fingerprint and headers.
  • The rule that matters: cf_clearance is cryptographically tied to the client IP, the User-Agent and the TLS fingerprint. Sending it through plain requests or urllib fails, because Python's OpenSSL fingerprint doesn't look like Chrome's BoringSSL. Use curl_cffi with impersonate="chrome124".

Method 3: standalone solving proxiesLink to Method 3: standalone solving proxies

  • FlareSolverr / Solverr: local Docker-based HTTP proxies that take your requests, clear Cloudflare challenges with headless Chromium or Camoufox, and hand back the HTML and cookies.

Open-source projectsLink to Open-source projects

Solvers and Cloudflare automation toolsLink to Solvers and Cloudflare automation tools

Repository Stack Highlights Link
sarperavci/CloudflareBypassForScraping Python (DrissionPage) A fast solver server for Turnstile and challenges sarperavci/CloudflareBypassForScraping
FlareSolverr/FlareSolverr TypeScript / Chromium The standard proxy server for getting past Cloudflare and DDoS-GUARD FlareSolverr/FlareSolverr
unseensnick/Solverr Python / Docker A FlareSolverr alternative that combines Camoufox and Chrome unseensnick/Solverr
xHossein/PyPasser Python Open-source solver for Turnstile, reCAPTCHA and anti-bot walls xHossein/PyPasser
ismoiloffS/EzSolver Python A local HTTP API that solves invisible and managed Turnstile automatically ismoiloffS/EzSolver
SolveGate/playwright-turnstile TypeScript / Playwright Helpers to read the sitekey, wait for the token and inject results SolveGate/playwright-turnstile
VeNoMouS/cloudscraper Python An older JS-challenge solver, only effective on basic or legacy setups VeNoMouS/cloudscraper

Anti-detect and stealth automationLink to Anti-detect and stealth automation

Repository Stack What it does Link
D4Vinci/Scrapling Python A stealth scraping framework with fetchers that handle Turnstile and interstitials D4Vinci/Scrapling
Kaliiiiiiiiii-Vinyzu/patchright-python Python (Playwright) A Playwright build with CDP leaks patched and human-like mouse movement Kaliiiiiiiiii-Vinyzu/patchright · Python
seleniumbase/SeleniumBase Python UC Mode with uc_gui_click_cf() for Turnstile seleniumbase/SeleniumBase
rebrowser/rebrowser-patches Node.js / Playwright / Puppeteer Removes the Runtime.enable leaks Cloudflare looks for rebrowser/rebrowser-patches
daijro/camoufox Python / C++ A stealth Firefox fork with spoofed hardware fingerprints daijro/camoufox
unclecode/crawl4ai Python An LLM-oriented crawler with Playwright stealth mode and anti-bot evasion unclecode/crawl4ai
omkarcloud/botasaurus Python / JS An all-in-one scraping framework with Cloudflare and anti-bot evasion built in omkarcloud/botasaurus
daijro/browserforge Python Generates statistically realistic headers, client hints and device fingerprints daijro/browserforge
g1879/DrissionPage Python Drives the browser over a CDP socket, without WebDriver g1879/DrissionPage
ultrafunkamsterdam/nodriver Python A next-generation async browser automation engine ultrafunkamsterdam/nodriver
berstend/puppeteer-extra Node.js A plugin framework that includes puppeteer-extra-plugin-stealth berstend/puppeteer-extra

TLS / JA3 / JA4 and HTTP/2 impersonationLink to TLS / JA3 / JA4 and HTTP/2 impersonation

Repository Stack What it does Link
lexiforest/curl_cffi Python / C Python bindings for curl-impersonate (JA3/JA4 and HTTP/2 fingerprints) lexiforest/curl_cffi
lwthiker/curl-impersonate C / Libcurl A curl build that reproduces browser TLS and HTTP handshakes lwthiker/curl-impersonate
bogdanfinn/tls-client Go / Python An HTTP client supporting complete TLS/JA3/JA4 fingerprint profiles bogdanfinn/tls-client

Official docs, labs and further readingLink to Official docs, labs and further reading

This page has no ready-to-run scripts. What follows is a map of official pages, live labs and write-ups to help you build your own integration or research.

Vendor documentationLink to Vendor documentation

Topic Why it matters Page
Turnstile overview It is separate from the CDN: the widget can run on a site that isn't proxied by Cloudflare Turnstile docs · Get started
Widget modes Managed, Non-Interactive, Invisible: when a checkbox shows and when it doesn't Widget concepts
Client embed api.js, implicit vs explicit render, data-sitekey, data-action, data-cdata, callbacks Client-side rendering
Siteverify POST /turnstile/v0/siteverify, response fields, error codes, a single-use token valid for 300 seconds Server-side validation
Dummy keys Predictable sitekey/secret pairs for CI, localhost and failure cases Testing
Challenge Pages Full-screen, managed and interactive challenges at the edge Challenges · Challenge types
JavaScript Detections Where cf_clearance and the js_detection.passed field come from JavaScript detections
Bot Management The 1–99 bot score, verified bots, custom rules Bot Management
JA3 / JA4 How the edge computes TLS fingerprints and where they appear in logs and the WAF JA3/JA4 fingerprint
Private Access Tokens Why Apple devices often skip the challenge entirely Eliminating CAPTCHAs with PATs
Product launch How Turnstile was first pitched as a reCAPTCHA replacement Turnstile GA announcement

Live pages worth opening in a browserLink to Live pages worth opening in a browser

Page What it shows
developers.cloudflare.com/turnstile/troubleshooting/testing The official dummy-key matrix and the expected XXXX.DUMMY.TOKEN.XXXX token
peet.it/turnstile A clean community widget demo next to a fingerprint lab
tls.peet.ws JA3/JA4, HTTP/2 and Client Hints for one session, handy to compare a browser with an HTTP client
turnstile.zerocdn.com A public bench for watching the iframe and the cf-turnstile-response field
nowsecure.nl The classic full-page Managed Challenge ("Just a moment…")
scrapingcourse.com/cloudflare-turnstile A Turnstile practice page
scrapingcourse.com/cloudflare-challenge An edge-challenge practice page
bot.sannysoft.com A quick list of the automation leaks Cloudflare also checks
abrahamjuliot.github.io/creepjs In-depth fingerprinting: canvas, WebGL, inconsistencies, headless

Write-ups and reference repositoriesLink to Write-ups and reference repositories


Practical engineering tips and troubleshootingLink to Practical engineering tips and troubleshooting

  1. IP reputation and ASN quality: datacenter IPs (AWS, Hetzner, DigitalOcean) get stuck in endless interactive challenges. Use clean ISP or residential proxies.
  2. Clearance is bound to the IP: cf_clearance is cryptographically tied to the outgoing IP. A cookie earned on IP A won't work on IP B.
  3. Keep the TLS stack consistent: never solve in a browser and then reuse the cookies in plain Python requests. Use curl_cffi or tls-client with a matching TLS/JA4 signature.
  4. Cross-origin iframes: the Turnstile widget lives in a cross-origin iframe, so a regular Playwright .click() can fail because of sandboxing. Click by coordinates or with anti-CDP mouse events (sb.uc_gui_click_cf()).
  5. Token lifetime: Turnstile tokens expire after 300 seconds (5 minutes) and can be used only once. Submit the form as soon as the token exists.

Skip the solver: let BrowserSolver handle Cloudflare Turnstile

Website AntiBot runs a real browser session with matching TLS, headers, cookies and IP, clears the challenge, and returns the page. You send a URL, you get HTML back.

Cloudflare Turnstile unlock guide →

For education and authorized testing only. Respect the law, privacy, and the terms of the sites you work with. Difficulty labels are editorial estimates. Adapted from the CC0 community field guide on GitHub.