Cloudflare Turnstile

​

What connecting it does

1. The widget loads Turnstile for you. On any page that has <botshield-verify>, the widget renders an invisible Turnstile challenge with your site key. No second script tag, no visible widget.
2. You receive the token with the result. The botshield:success event carries turnstile_token alongside token and request_id. Validate it with Cloudflare siteverify on your server, and decline the submission if it fails.
3. Fail closed. Require both: a valid Turnstile token and a verified BotShield result. A missing or failed Turnstile token means the request did not come through the widget on a real page.

​

Connect it in the Console

​

Validate the token on your server

const TURNSTILE_VERIFY_URL = "https://challenges.cloudflare.com/turnstile/v0/siteverify";

async function turnstilePassed(token: string, secret: string, ip?: string): Promise<boolean> {
  if (!token) return false;
  const body = new URLSearchParams({ secret, response: token });
  if (ip) body.set("remoteip", ip);
  const res = await fetch(TURNSTILE_VERIFY_URL, { method: "POST", body });
  if (!res.ok) return false;
  const result = (await res.json()) as { success: boolean };
  return result.success === true;
}

<botshield-verify site-key="pk_live_…" scope="signup" scan-mode="modal"></botshield-verify>

<script>
  document.addEventListener("botshield:success", ({ detail }) => {
    // detail.token (Live) or detail.request_id (Recent Presence), plus detail.turnstile_token
    submitSignup({
      botshield_token: detail.token,
      botshield_request_id: detail.request_id,
      turnstile_token: detail.turnstile_token,
    });
  });
</script>

​

What it is not

• Not a score. BotShield does not read, weigh, or store the Turnstile result. The gate’s answer is the human check.
• Not required. Every BotShield Gate works without it.
• Not a substitute. Turnstile tells you a browser session looks human enough to proceed. BotShield Gate tells you a real person confirmed, with a signed result your server can check.

​

Next steps