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.

Prerequisites

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

---

Process

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.

Component	Description
Sitekey	Public key used to invoke the Turnstile widget on your site.
Secret key	Private key used for server-side token validation.
Configurations	Mode, hostnames, appearance settings, and other options.

Important

Regardless of how you create and manage your widgets, you will still need to embed the widget on your webpage and validate the token on your server.

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.

---

Implementation

Follow the steps below to implement Turnstile.

1. Create your widget

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

Select your preferred implementation method:

Cloudflare dashboard

API

Terraform

2. Embed the widget

Add the Turnstile widget to your webpage forms and applications.

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

Testing

You can test your Turnstile widget on your webpage without triggering an actual Cloudflare Challenge by using a testing sitekey.

Refer to Testing for more information.

3. Validate tokens

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.

Testing

You can test the dummy token generated with testing sitekey via Siteverify API with the testing secret key. Your production secret keys will reject dummy tokens.

Refer to Testing for more information.

Additional implementation options

Mobile configuration

Special considerations are necessary for mobile applications and WebView implementations.

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

Migration from other CAPTCHAs

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.

---

Security requirements

• 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.

---

Best practices

Security

• 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.

Operational

• 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.