Extension for browsers

For business

Pricing

Blog

Docs

Cloudflare Turnstile
and CapMonster Cloud

CAPTCHA solving, website installation and testing.

Inherited a site with a captcha or another protection layer but no access to the source code? In that case you naturally ask: which solution is installed, is it configured correctly, and how can the workflow be tested?

In this article, we have tried to answer all the key questions. The first step in solving the task is to determine which protection system is being used. To do this, you can refer to the list of popular captchas and anti-bot protection systems, where you will find visual examples and key indicators that help you quickly understand what you are dealing with.

If you discover that your site uses Cloudflare Turnstile, the next step is to study its properties and operation in more detail. In this article, you can also review the instructions on how to integrate Cloudflare Turnstile so that you fully understand how it functions on your site. This will help you not only understand the current protection, but also properly plan its maintenance.

What is Cloudflare Turnstile

Cloudflare Turnstile is a modern CAPTCHA from Cloudflare that protects websites from automated actions. For website visitors, the verification is almost invisible, with no need to complete tasks: usually a single click on the checkbox is enough, after which the system decides whether to let the visitor through or block them if a bot is suspected. Unlike Cloudflare Challenge, Turnstile CAPTCHA is placed directly on the website, not in a separate window—typically in login or registration forms.

How to solve Cloudflare Turnstile via CapMonster Cloud

When testing forms that include Cloudflare Turnstile, you often need to verify that the captcha works and is integrated correctly.

You can verify the captcha embedded on your site manually.

Open the form page and make sure the captcha renders.
Try submitting the form without solving it — the server should return an error.
After a successful solution, the form must be submitted without issues.

For automatic solving you can use tools like CapMonster Cloud, which accepts captcha parameters, processes them on its servers, and returns a ready-to-use token. Insert this token into the form to pass the check without user interaction.

Working with CapMonster Cloud via API typically involves the following steps:

Creating a task

At this stage, you pass your API key, CAPTCHA type, and its parameters. The service returns a unique taskId, which can later be used to retrieve the result.

Sending an API request

The request to solve Cloudflare Turnstile must specify the following parameters:

type - TurnstileTask;

websiteURL - address of the page where the CAPTCHA is being solved;

websiteKey - Turnstile key.

Find more details about the parameters and how to gather them automatically before sending a task in the CapMonster Cloud documentation.

Endpoint for sending the task:

https://api.capmonster.cloud/createTask

Request example:

{
  "clientKey": "API_KEY",
  "task": {
    "type": "TurnstileTask",
    "websiteURL": "http://tsmanaged.zlsupport.com",
    "websiteKey": "0x4AAAAAAABUYP0XeMJF0xoy"
  }
}

Response:

{
  "errorId":0,
  "taskId":407533072
}

Receiving the result

After creating the task, poll the solution status.

Address to receive the result:

https://api.capmonster.cloud/getTaskResult

Request example:

{
  "clientKey":"API_KEY",
  "taskId": 407533072
}

Response:

{
  "errorId": 0,
  "status": "ready",
  "solution": {
    "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/142.0.0.0 Safari/537.36",
    "token": "0.iGX3xsyFCkbGePM3jP4P4khLo6TrLukt8ZzBvwuQOvbC...f61f3082"
  }
}

Placing the token on the page

After the server receives the Turnstile token from CapMonster Cloud, it needs to be passed to the website. The server will verify the data and confirm that the CAPTCHA has been successfully solved. For automation, you can use HTTP requests or tools like Puppeteer, Selenium, or Playwright—they allow you to insert values into the form and send the request, emulating user actions.

Cloudflare Turnstile recognition using ready-made libraries

The CapMonster Cloud service provides ready-made libraries for convenient work in Python, JavaScript (Node.js), and C#.

Python

JavaScript

Solving, token insertion, and form submission

Example in Node.js for the complete cycle of CAPTCHA recognition on your webpage. Possible approaches: use HTTP requests to retrieve HTML and CAPTCHA parameters, send the response and process the result; or with automation tools (e.g., Playwright)—open the page, wait for the CAPTCHA, send parameters (for testing you can send both correct and incorrect data), get the solution via CapMonster Cloud client, insert the token into the form and see the result.

// npm install playwright @zennolab_com/capmonstercloud-client

import { chromium } from "playwright";
import { CapMonsterCloudClientFactory, ClientOptions, TurnstileRequest } from "@zennolab_com/capmonstercloud-client";

async function main() {
  // 1. Solving Turnstile via CapMonster Cloud
  const cmcClient = CapMonsterCloudClientFactory.Create(
    new ClientOptions({ clientKey: 'YOUR_CAPMONSTER_API_KEY' })
  );

  const turnstileRequest = new TurnstileRequest({
    websiteURL: 'http://tsmanaged.zlsupport.com',
    websiteKey: '0x4AAAAAAABUYP0XeMJF0xoy',
  });

  const result = await cmcClient.Solve(turnstileRequest);
  const token = result.solution.token;
  console.log('Turnstile token received:', token);

  // 2. Starting Playwright
  const browser = await chromium.launch({ headless: false });
  const context = await browser.newContext();
  const page = await context.newPage();
  await page.goto('http://tsmanaged.zlsupport.com');

  // 3. Filling in login and password
  await page.fill('#username', 'your_username');
  await page.fill('#password', 'your_password');

  // 4. Waiting for the hidden token field to appear
  await page.waitForSelector('#token', { state: 'attached', timeout: 60000 });

  // 5. Inserting token and making field visible
  await page.evaluate((t) => {
    const tokenInput = document.querySelector('#token');
    if (tokenInput) {
      tokenInput.type = 'text';  // make field visible
      tokenInput.value = t;      // insert token
      console.log('Token inserted into token field');
    } else {
      console.error('Field #token not found');
    }
  }, token);

  // 6. Verifying that the token was actually inserted
  const checkValue = await page.$eval('#token', el => el.value);
  console.log('Checking the token value:', checkValue);

  // 7. Submitting form
  await page.click('button[type="submit"]');
  console.log('Form submitted with Turnstile token');

  // await browser.close();
}

main().catch(err => console.error(err));

There's also an excellent option to test CAPTCHA recognition using the CapMonster Cloud browser extension, which allows you to quickly check CAPTCHA functionality directly on the page and track the solving process in real-time without writing code—available for installation in Chrome and Firefox.

How to connect Cloudflare Turnstile to your website

To confidently navigate how CAPTCHA works on your website, understand its verification logic, reconnect or reconfigure it, we recommend studying this section. It describes the process of connecting protection—this will help you quickly understand all the nuances.

1. Go to the Cloudflare Turnstile page, click Get Started.

2. Register with the service.

3. In Turnstile Widgets, click the blue Add Widget button.

HowTo Connect image 1

4. Configure Cloudflare Turnstile, specify:

Widget name—name of the CAPTCHA (for convenience, e.g., Login form).
Hostname Management—domains where the CAPTCHA will work (e.g., example.com).
Widget Mode:
- Managed—optimal option, CAPTCHA decides itself whether to show the checkbox.
- Non-interactive—verification is performed automatically without clicks.
- Invisible—completely invisible.
Pre-clearance—set to Yes if the site is through Cloudflare Proxy (to avoid repeating the CAPTCHA).

5. After creating the widget, you'll receive two keys—Site Key and Secret Key.

HowTo Connect image 2

6. Connect the client-side part

1) Connect the Turnstile script

Automatic rendering (widget is created automatically when the page loads):

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

Programmatic control (you create the widget yourself via JavaScript):

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

Important: the script must be loaded from the exact URL. Proxy or cache may cause failures.

2) Create a container for the widget

Auto:

<div class="cf-turnstile" data-sitekey="<YOUR_SITEKEY>"></div>

Programmatically:

<div id="turnstile-container"></div>

3) Widget configuration

Via data attributes:

<div class="cf-turnstile"
            data-sitekey="<YOUR_SITEKEY>"
            data-theme="light"
            data-size="normal"
            data-callback="onSuccess">
          </div>

Via JavaScript:

const widgetId = turnstile.render("#turnstile-container", {
  sitekey: "<YOUR_SITEKEY>",
  theme: "light",
  size: "normal",
  callback: token => console.log("Token:", token)
});

4) Working with tokens

const token = turnstile.getResponse(widgetId);      // get token
const isExpired = turnstile.isExpired(widgetId);    // check expiration
turnstile.reset(widgetId);                          // reset
turnstile.remove(widgetId);                         // remove
turnstile.execute("#turnstile-container");         // manual execution

5) Integration with form

<form id="my-form" method="POST">
  <input type="hidden" name="cf-turnstile-response" id="cf-turnstile-response">
  <button type="submit">Submit</button>
</form>

<script>
function onSuccess(token) {
  document.getElementById("cf-turnstile-response").value = token;
}
</script>

Code example

<title>Turnstile Example</title>
  <!-- Connect Turnstile script -->
  <script src="https://challenges.cloudflare.com/turnstile/v0/api.js" async defer></script>
</head>
<body>
  <h1>Form example with Turnstile</h1>

  <form id="my-form">
    <label for="username">Name:</label>
    <input type="text" name="username" id="username" required>
    
    <!-- Container for Turnstile -->
    <div class="cf-turnstile" data-sitekey="<YOUR_SITEKEY>" data-callback="onTurnstileSuccess"></div>
    
    <button type="submit">Submit</button>
  </form>

  <script>
    // Callback that is called after passing the CAPTCHA
    function onTurnstileSuccess(token) {
      console.log("Received Turnstile token:", token);
      // Save token to hidden form field (optional)
      document.getElementById("cf-turnstile-token")?.remove();
      const input = document.createElement("input");
      input.type = "hidden";
      input.name = "cf-turnstile-response";
      input.id = "cf-turnstile-token";
      input.value = token;
      document.getElementById("my-form").appendChild(input);
    }

    // Form submission
    document.getElementById("my-form").addEventListener("submit", async (e) => {
      e.preventDefault();

      const formData = new FormData(e.target);
      const response = await fetch("/submit-form", {
        method: "POST",
        body: formData
      });

      const result = await response.json();
      if(result.success){
        alert("Form successfully submitted and token verified!");
      } else {
        alert("Turnstile token verification error. Please try again.");
        // Reset widget so the user can complete the CAPTCHA again
        turnstile.reset();
      }
    });
  </script>
</body>
</html>

6) Configure the server-side part

Server-side verification process:

Client: user completes Turnstile on the page → token is created.
Form is submitted: token along with form data is sent to the server.
Server: makes a POST request to Cloudflare Siteverify API with token and secret.
Cloudflare: returns JSON with result (success: true/false) and additional information (action, hostname, completion time).
Server: decides whether to allow or reject the user action.

Siteverify API:

POST

https://challenges.cloudflare.com/turnstile/v0/siteverify

Request parameters:

secret (required): secret Turnstile key from Cloudflare panel
response (required): token received on the client
remoteip (optional): user's IP address (recommended)
idempotency_key (optional): unique UUID for protection against repeated verifications

Token properties:

Maximum length: 2048 characters
Valid for 5 minutes
Single-use
When expired or re-verified, the API will return timeout-or-duplicate error

Verification example in PHP

<?php
function validateTurnstile($token, $secret, $remoteip = null) {
    $url = 'https://challenges.cloudflare.com/turnstile/v0/siteverify';
    $data = ['secret' => $secret, 'response' => $token];
    if ($remoteip) $data['remoteip'] = $remoteip;

    $options = [
        'http' => [
            'header'  => "Content-type: application/x-www-form-urlencoded
",
            'method'  => 'POST',
            'content' => http_build_query($data)
        ]
    ];

    $response = file_get_contents($url, false, stream_context_create($options));
    if ($response === FALSE) {
        return ['success' => false, 'error-codes' => ['internal-error']];
    }

    return json_decode($response, true);
}

// Usage
$secret_key = 'YOUR_SECRET_KEY';
$token = $_POST['cf-turnstile-response'] ?? '';
$remoteip = $_SERVER['REMOTE_ADDR'];

$result = validateTurnstile($token, $secret_key, $remoteip);

if($result['success']){
    echo "Form successfully submitted!";
} else {
    echo "Verification error: " . implode(', ', $result['error-codes']);
}
?>

All detailed instructions for installing and configuring Cloudflare Turnstile, including client and server integration, code examples, error descriptions, and security recommendations, can be found in the official Cloudflare documentation.

Possible errors and debugging

Incorrect parameters

CAPTCHA doesn't display or returns errors like invalid-input-secret, missing-input-response, invalid-input-response. Check the validity of sitekey and secret key, as well as settings in Cloudflare Dashboard.

Solution timeout

Token has expired (valid for 300 seconds) or wasn't received in time. Ensure stable connection and correct API integration.

Empty or incorrect token

Parameter cf-turnstile-response is missing or incorrect. Check the token transfer to the form and server.

Response success=false

Token is invalid, expired, or already used. Each token can only be verified once. Enable logging of Siteverify requests and responses for analysis.

Protection resilience checks

After integration, make sure the system really protects the site from automated actions.

Try executing the request without solving the CAPTCHA—the server should return success: false.

Conduct load testing (for example, using k6 or JMeter) at speeds over 100+ requests per second. Turnstile should correctly process requests, and the server should stably verify tokens through the Siteverify API.

Check the response to expired or resubmitted tokens—expected API response: success: false and error-codes: ["timeout-or-duplicate"].

Security and optimization tips

Verify tokens only on the server, never call the Siteverify API from the frontend—this will expose your secret key.

Verify tokens only on the server, never call the Siteverify API from the frontend—this will expose your secret key.

Use environment variables or a secret management system rather than storing keys in code.

Use environment variables or a secret management system rather than storing keys in code.

Check additional fields (<b>hostname</b>, <b>action</b>) to ensure the request came from your website.

Check additional fields (hostname, action) to ensure the request came from your website.

Use HTTPS—all calls to Siteverify should be made over a secure connection.

Implement error handling—when the API is unavailable, show the user a clear message without revealing internal data.

Implement error handling—when the API is unavailable, show the user a clear message without revealing internal data.

Restrict sitekey usage by domains.

Add links to the <b>Privacy Policy</b> and <b>Cloudflare Terms of Service</b> to the form if required by your organization or privacy policy.

Add links to the Privacy Policy and Cloudflare Terms of Service to the form if required by your organization or privacy policy.

Conclusion

If you’ve taken over a website that already has a captcha or another protection system installed, but you don’t have access to the code, don’t worry! It’s quite easy to identify which technology is being used. To verify that everything works correctly, you can use the CapMonster Cloud recognition service in an isolated test environment to make sure that the token processing mechanism and the validation logic are functioning properly.

In the case of Cloudflare Turnstile, it’s enough to detect the system, observe its behavior, and confirm that the protection is working correctly. In this article, we showed how to identify Cloudflare Turnstile and where to find instructions on how to integrate or reconfigure it, so you can confidently maintain the protection and keep its operation under control.

Helpful links

Cloudflare Turnstile Documentation →

CapMonster Cloud Documentation (working with Cloudflare Turnstile) →

What is Cloudflare CAPTCHA and how to solve it with CapMonster Cloud →

How Cloudflare detects automated traffic: protecting websites from bots →

The CapMonster Cloud browser extension is available for Chrome and Firefox. Full installation and usage instructions are available here.

Cloudflare Turnstile and CapMonster Cloud

Cloudflare Turnstile
and CapMonster Cloud