Skip to content
/
Cloudflare Turnstile
Last updated

Cloudflare Turnstile

Cloudflare Turnstile is a modern, privacy-focused CAPTCHA alternative developed by Cloudflare. It functions similarly to reCAPTCHA but without tracking user behavior. Turnstile appears as a widget on forms and verifies users with minimal interaction—often invisibly.

You’ll typically encounter Turnstile in two contexts:

  1. Standalone widget embedded directly in a website’s form.
  2. Cloudflare interstitial challenge pages (e.g., during DDoS protection), where Turnstile appears as part of a browser verification gate.

Cloudflare Turnstile Widget

Integration Workflow

1. Gather Required Parameters

  • Site Key: Found in data-sitekey or the sitekey property of turnstile.render(...).
  • Page URL: The full URL where Turnstile is active (must match exactly, especially on Cloudflare challenge pages).

Tip: On dynamic or Cloudflare challenge pages, override turnstile.render() in the browser console to log exact parameters before the widget loads.

2. Submit the Task

  • For API V1: Use in.php with method=turnstile, sitekey, and pageurl. Include optional fields as form parameters.
    → See API V1 – Cloudflare Turnstile
  • API V2 COMING SOON

3. Receive a Task ID and Wait

Solving typically takes 10–15 seconds.

4. Poll for the Result

  • API V1: via res.php
    → See respective Get Result endpoints.
  • API V2 COMING SOON

5. Apply the Token

Depending on the implementation:

  1. Field Injection: Inject the token into the hidden field:

    // Primary field
document.querySelector('[name="cf-turnstile-response"]').value = "TOKEN_FROM_CAPTCHAAI";

// Fallback (some sites reuse reCAPTCHA field)
const fallback = document.getElementById("g-recaptcha-response");
if (fallback) fallback.value = "TOKEN_FROM_CAPTCHAAI";

    Then submit the form.

  2. Callback Function: Submit the token using the callback function:

    To get the callback function + the required parameters you can inject the following JavaScript on page before the Turnstile widget is loaded.

    const i = setInterval(()=>{
if (window.turnstile) {
    clearInterval(i)
    window.turnstile.render = (a,b) => {
    let p = {
        method: "turnstile",
        sitekey: b.sitekey,
        pageurl: window.location.href,
        userAgent: navigator.userAgent
    }
    console.log(JSON.stringify(p))
    window.tsCallback = b.callback
    return 'captchaai'
    }
}
},10)

    Then when you get the token from our API use the following code to submit the token using the callback function

    window.tsCallback('YOUR_TOKEN_HERE');

Important: The token is single-use and tied to the exact page URL and context.

Previous page
Next page