skip to content

Bot Scores & Turnstile

Bot management scores each request from 1 to 99, and Turnstile proves a visitor is human without a puzzle. Interviewers ask how to stop bad bots without blocking verified crawlers.

on this pageshow

explore

questions

6

With Cloudflare Turnstile, how do you protect a marketplace's sign-up form, and why must the server call siteverify instead of trusting the widget?

level: juniorimportance: must knowfreq 50%

answer

  1. public sitekey, private secret key
  2. hidden cf-turnstile-response field
  3. server-side POST to siteverify
  4. 300 seconds, spendable once

basics

~20 s

Embed the Turnstile widget with its public sitekey so the form submits a token in cf-turnstile-response. The server posts that token and the secret key to siteverify and creates the account only on success; an unchecked token proves nothing.

solid answer

~40 s

A Turnstile widget has a public **sitekey** and a private **secret key**. Load `api.js` from `challenges.cloudflare.com`, put a `cf-turnstile` div with `data-sitekey` inside the sign-up form, and the widget runs its challenge in the browser and adds a hidden `cf-turnstile-response` field holding a token. On submit, the server POSTs `secret`, `response` and optionally `remoteip` to `https://challenges.cloudflare.com/turnstile/v0/siteverify` and creates the account only when `success` is true, ideally also checking `hostname` and `action`. The widget alone protects nothing: a script can post the form with an invented string, and a token is valid for 300 seconds and only once, so only siteverify can tell a real, fresh, unspent token from a forged or replayed one.

code

html · 7 lines
html
<form action="/signup" method="POST">
  <input type="email" name="email" autocomplete="email" required />
  <input type="password" name="password" autocomplete="new-password" required />
  <div class="cf-turnstile" data-sitekey="<YOUR-SITE-KEY>" data-action="signup"></div>
  <button type="submit">Create account</button>
</form>
<script src="https://challenges.cloudflare.com/turnstile/v0/api.js" async defer></script>

go deeper

for a junior

Recall the two keys and the two halves: the sitekey and widget in the page, the secret key and siteverify on the server. Say plainly that a form without siteverify is unprotected.

for a middle

Explain the token's life: written to cf-turnstile-response, valid for 300 seconds, spendable once, checked by siteverify, and what success, hostname and action each tell the server.

for a senior

Show production hygiene: the secret held as a server-side secret, one validation per token, dummy keys in CI, hostnames restricted to your own domains, and Turnstile Analytics watched for widgets with no validations.

for a principal

Place Turnstile among the bot controls: a per-form proof of a human, separate from site-wide bot scores, and decide which flows earn a widget so friction lands only where abuse costs money.

## What Turnstile does **Turnstile** is Cloudflare's check that a visitor is a person rather than a script, without an image puzzle. It runs as a JavaScript widget in the visitor's browser, collects client-side signals and runs challenges, and when it is satisfied it produces a **token**: an opaque string of up to 2,048 characters. Your server then asks Cloudflare whether that token is genuine. Both halves are required; the widget on its own is decoration. Turnstile is an independent service. It works on any site, whether or not the site's traffic is proxied through Cloudflare, so a marketplace can put it on a sign-up form wherever that form is served from. Each **widget** you create (in the dashboard or through the API) has: - a **sitekey**, the public identifier you place in HTML; - a **secret key**, the private credential only your server uses; - a **mode**: Managed (recommended; asks for a checkbox click only when a further check is needed), Non-Interactive (a visible spinner, no interaction) or Invisible (nothing shown); - a list of **hostnames** where the widget may load; adding a hostname also allows its subdomains. ## The client side With implicit rendering, the page loads the script and declares a container: 1. Add `<script src="https://challenges.cloudflare.com/turnstile/v0/api.js" async defer>`. The file must be fetched from that exact URL; proxying or caching it breaks the widget when Cloudflare updates it. 2. Place `<div class="cf-turnstile" data-sitekey="...">` inside the `<form>`. 3. Optionally set `data-action="signup"`, a label of up to 32 characters that siteverify returns, so one sitekey can serve several forms and the server can check which form a token was minted for. When the challenge succeeds, the widget writes the token into a hidden input named `cf-turnstile-response` (renamable with `data-response-field-name`) and calls any `data-callback` you set. Single-page apps use explicit rendering with `turnstile.render()` and read the token from the callback or from `turnstile.getResponse(widgetId)`. ## The server side: siteverify The form handler takes the token and sends it to the **Siteverify API**: - endpoint: `POST https://challenges.cloudflare.com/turnstile/v0/siteverify`, with a JSON or form-encoded body; - required: `secret` (the widget's secret key) and `response` (the token); - optional: `remoteip` (the visitor's IP, for example from `CF-Connecting-IP`) and `idempotency_key` (a UUID that makes a retry of the same validation safe). The JSON answer carries `success`, `error-codes`, `challenge_ts`, `hostname`, `action` and `cdata`. Accept the request only when `success` is true and, where you set them, when `hostname` is your domain and `action` is the form you expected. | Answer | What it tells the server | | --- | --- | | `success: true` | A challenge was solved for this widget and the token had not been spent | | `invalid-input-response` | The token is malformed or not one Cloudflare issued | | `timeout-or-duplicate` | The token has already been validated once | | `invalid-input-secret` | The secret key is wrong or no longer valid | ## Why the widget alone protects nothing The browser is the attacker's machine. Three facts make the server-side call mandatory: - **Tokens can be forged.** A script can post your form with any string in `cf-turnstile-response` without ever loading the widget. Only siteverify knows whether Cloudflare issued that string. - **Tokens expire.** Each is valid for 300 seconds after it was generated, so a token farmed earlier fails validation later. - **Tokens are single-use.** A second validation of the same token fails with `timeout-or-duplicate`, so one solved challenge cannot be replayed across a thousand sign-ups. A form that renders the widget but never calls siteverify also shows zero token validations in Turnstile Analytics, which is often how a team discovers the gap. ## Keeping the secret secret The secret key belongs on the server only: in a Worker it is a secret rather than a value in the page, and in any other backend an environment variable or a secret store. Calling siteverify from front-end code would publish the key and let anyone vouch for their own tokens. If a key leaks, **Rotate Secret Key** in the widget's settings issues a new one, and the old and new keys both stay valid for two hours while you deploy it. For automated tests, Cloudflare publishes dummy keys: the sitekey `1x00000000000000000000AA` always passes and the secret `1x0000000000000000000000000000000AA` always validates, while production secret keys reject the dummy tokens. Keep `localhost` off a production widget's hostname list.

  • What do data-action and the hostname field add to a Turnstile siteverify check?
    `data-action` labels a widget (up to 32 letters, digits, `_` or `-`) and siteverify echoes it as `action`, so a token minted on the newsletter form cannot be spent on sign-up. `hostname` reports where the challenge was served, confirming the token came from your own page. Both are checked after `success` is true: they narrow what a valid token may be used for.
  • Which Turnstile widget mode suits a marketplace sign-up form, and why?
    Managed mode, which Cloudflare recommends: it runs non-interactively for most visitors and shows a single checkbox only when its signals call for a further check, with no images or text to decipher. Non-Interactive and Invisible never ask for interaction, trading a little assurance for zero friction. Whichever mode you choose, the server-side siteverify call is the same.
  • How do you test a Turnstile-protected form in CI without real challenges?
    Use Cloudflare's dummy keys: the sitekey `1x00000000000000000000AA` always passes, `2x00000000000000000000AB` always fails, and the secret `1x0000000000000000000000000000000AA` always validates while `3x0000000000000000000000000000000AA` returns a token-already-spent error. Dummy keys work on any domain, including `localhost`, and production secret keys reject dummy tokens, so a test key cannot leak into production unnoticed.

A Turnstile token works like a numbered cloakroom ticket: the attendant who issued it checks the number against their own book and tears the ticket up when the coat is collected. A ticket drawn at home fails the book check, and the same ticket cannot collect a second coat.

  • The widget's success callback proves the visitor is human, so the server can skip siteverify.
  • The secret key can sit in front-end JavaScript beside the sitekey.
  • Turnstile only works on sites whose traffic is proxied through Cloudflare.
  • One Turnstile token can be reused for every form the visitor submits in a session.
  • Turnstile makes every visitor solve an image puzzle.
open as a page

In Cloudflare Bot Management, what does a bot score from 1 to 99 mean, and how do you act on cf.bot_management.score in a rule?

level: middleimportance: must knowfreq 42%

basics

~20 s

The bot score is Cloudflare's confidence that a request is automated: 1 almost certainly a bot, 2-29 likely automated, 30-99 likely human, 0 not scored. Enterprise Bot Management exposes it as cf.bot_management.score for custom rules, Workers and logs.

open as a page

In Cloudflare, how do Bot Fight Mode, Super Bot Fight Mode and Bot Management for Enterprise differ in plan, control and exceptions?

level: middleimportance: should knowfreq 36%

basics

~20 s

Bot Fight Mode (Free) challenges bot patterns site-wide and no custom rule can skip it. Super Bot Fight Mode (Pro and up) adds per-group actions and Skip exceptions. Bot Management for Enterprise exposes a per-request score and fields for custom rules.

open as a page

A Cloudflare Turnstile-protected sign-up endpoint rejects some genuine users because siteverify returns timeout-or-duplicate; what causes it, and how do you fix it?

level: seniorimportance: should knowfreq 28%

basics

~20 s

timeout-or-duplicate means the token was already validated or outlived its 300 seconds: a second verifier, a retried request, a resubmitted form or a stale copy. Validate each token once, retry siteverify with an idempotency_key, and reset the widget before resubmitting.

open as a page

After a marketplace's Cloudflare custom rule blocked bot scores below 30, its search crawlers and in-house uptime checker were blocked too; why, and what fixes each?

level: seniorimportance: should knowfreq 34%

basics

~10 s

Crawlers and checkers are automated, so they score below 30. Adding not cf.bot_management.verified_bot lets Cloudflare's verified crawlers pass; the in-house checker is not verified, so it needs a narrowly scoped Skip rule placed first.

open as a page

A marketplace's own mobile app gets low Cloudflare bot scores on its checkout API; how do you use JA3 or JA4 fingerprints to let it through safely?

level: seniorimportance: nice to knowfreq 22%

basics

~20 s

A native app's TLS stack usually yields the same JA3 or JA4 fingerprint across devices. Find it in Security Analytics, then add a Skip rule matching cf.bot_management.ja4 together with the app's API host and path, placed before the score rule.

open as a page