Cloudflare Turnstile: stop bots without annoying CAPTCHAs

The moment you put a public form online, bots find it. Sign-up forms, contact forms, comment boxes. You need a way to tell humans from scripts.

The old answer was a CAPTCHA: squint at blurry traffic lights. Turnstile is Cloudflare’s replacement. Most of the time the user does nothing at all, it just checks a box for them in the background.

It works in two halves: a widget on your page, and a check on your server. Let me show both.

Get your keys

In the Cloudflare dashboard, you create a Turnstile widget and get two keys:

• a site key, which is public and goes in your HTML
• a secret key, which stays on your server

The word “key” hides the difference, so keep the rule mechanical: the site key ships to the client, the secret key never does. A leaked site key is harmless. A leaked secret key lets anyone forge “this is a human” verdicts against your backend. If you ever spot the secret in client code or logs, rotate it.

For trying things out, Cloudflare has test keys that always pass. The site key 1x00000000000000000000AA and the secret 1x0000000000000000000000000000000AA are handy while you build.

My advice is to also create separate widgets for staging and production, and restrict the production widget to your real hostnames in the widget settings. That way a token solved on someone else’s domain can’t be spent against your forms.

Add the widget

On your page, load the Turnstile script and drop in a div with your site key:

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

<form method="POST" action="/submit">
  <input type="email" name="email" required />
  <div class="cf-turnstile" data-sitekey="your-site-key"></div>
  <button type="submit">Sign up</button>
</form>

That’s the whole frontend. The widget runs, and when it passes, it adds a hidden field called cf-turnstile-response to your form. That field holds a token.

Verify on the server

A token from the page isn’t proof on its own. A bot could fake the form post. So your Worker must ask Cloudflare “is this token real?” using your secret key.

export default {
  async fetch(request, env) {
    const form = await request.formData()
    const token = form.get('cf-turnstile-response')

    const result = await fetch(
      'https://challenges.cloudflare.com/turnstile/v0/siteverify',
      {
        method: 'POST',
        body: new URLSearchParams({
          secret: env.TURNSTILE_SECRET_KEY,
          response: token,
        }),
      }
    )

    const outcome = await result.json()

    if (!outcome.success) {
      return new Response('Failed the bot check', { status: 403 })
    }

    // The user is human, handle the form
    return new Response('Thanks!')
  },
}

The flow is: read the token from the form, POST it to the siteverify endpoint with your secret, and check outcome.success. Only then do you trust the submission.

Two properties of the token are worth knowing. It expires after about five minutes, and it can be validated exactly once. A second siteverify call with the same token fails with a timeout-or-duplicate error code. That single-use behavior is your replay protection: call siteverify once per submission and act on its result.

And one thing to never do: don’t call siteverify from browser JavaScript. That would mean shipping the secret key to the client, where anyone can read it. It’s a server-to-server call.

Keep the secret key as a Cloudflare secret, not in your code:

npx wrangler secret put TURNSTILE_SECRET_KEY

Why I like it

Turnstile is free, it’s privacy-friendly, and for real users it’s usually invisible. No puzzles, no friction.

The one rule to never break: always verify the token on the server. The widget on its own can be bypassed. The server check is what actually stops the bots.

The full reference is in the Turnstile docs.