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?
answer
- public sitekey, private secret key
- hidden cf-turnstile-response field
- server-side POST to siteverify
- 300 seconds, spendable once
basics
~20 sEmbed 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 sA 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<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
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.
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.
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.
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.