Get started

Turnstile protects your website forms from bots. It works in two steps: a JavaScript widget runs challenges in the visitor's browser and produces a token, then your server sends that token to Cloudflare to confirm it is valid. This guide covers how to set up both steps.

Before you begin, you must have:

• A Cloudflare account
• A website or web application to protect
• Basic knowledge of HTML and your preferred server-side language

A Turnstile widget is an instance of Turnstile embedded on your webpage. Each widget has a sitekey (a public identifier you place in your HTML) and a secret key (a private credential your server uses to validate tokens).

Each widget gets its own unique sitekey and secret key pair, and options for configurations.

Implementing Turnstile involves two essential components that work together:

1. Client-side: Embed the widget

   Add the Turnstile widget to your webpage to challenge visitors and generate tokens. A token is a string (up to 2,048 characters) generated when the visitor completes a challenge.

2. Server-side: Validate the token

   Send tokens to Cloudflare's Siteverify API the endpoint for validating Turnstile tokens to confirm they are authentic and have not been tampered with.

Turnstile is designed to be an independent service. You can use Turnstile on any website, regardless of whether it is proxied through the Cloudflare network. This allows for flexible deployment across multi-cloud environments, on-premises infrastructure, or sites using other CDNs. The client-side widget and server-side validation steps are completely self-contained.

Refer to Implementation below for guidance on how to implement Turnstile on your website.

Follow the steps below to implement Turnstile.

First, you must create a Turnstile widget to get your sitekey and secret key.

Select your preferred implementation method:

Add the Turnstile widget to your webpage forms and applications.

Refer to Embed the widget to learn more about implicit and explicit rendering methods.

Implement server-side validation to verify the tokens generated by your widgets.

Refer to Validate the token to secure your implementation with proper token verification.

Special considerations are necessary for mobile applications and WebView implementations.

Refer to Mobile implementation for more information on mobile application integration.

If you are currently using reCAPTCHA, hCaptcha, or another CAPTCHA service, Turnstile can be a drop-in replacement. You can copy and paste our script wherever you have deployed the existing script today.

Refer to Migration for step-by-step migration guidance from other CAPTCHA services.

• Server-side validation is mandatory. It is critical to enforce Turnstile tokens with the Siteverify API. The Turnstile token could be invalid, expired, or already redeemed. Not verifying the token will leave major vulnerabilities in your implementation. You must call Siteverify to complete your Turnstile configuration. Otherwise, it is incomplete and will result in zeroes for token validation when viewing your metrics in Turnstile Analytics.

• Tokens expire after 300 seconds (5 minutes). Each token can only be validated once. Expired or used tokens must be replaced with fresh challenges.

• Protect your secret keys. Never expose secret keys in client-side code.
• Rotate your keys regularly. Use API or dashboard to rotate secret keys periodically.
• Restrict your hostnames. Only allow widgets on domains that you control.
• Monitor the usage. Use analytics to detect unusual patterns.

• Use descriptive names. Name widgets based on their purpose, such as "Login Form" or "Contact Page".
• Separate your environments. Use different widgets for development, staging, and production.
• Keep track of which widgets are used at which locations.
• Store your widget configurations in version control when using Terraform.