Cloudflare Turnstile Setup

Cloudflare Turnstile is a privacy-preserving alternative to traditional CAPTCHAs that provides invisible protection against automated abuse. It runs in the background without user interaction, offering a seamless experience while maintaining robust security.

Quick Setup with BasinJS (Recommended)

The easiest way to implement Cloudflare Turnstile is using BasinJS, our JavaScript helper library. BasinJS handles all the setup automatically for any of our supported CAPTCHA solutions.

To use BasinJS, follow the steps outlined in our BasinJS Documentation.

About Cloudflare Turnstile

Cloudflare Turnstile offers several advantages:

Privacy-First: Runs without collecting personal data
Invisible Protection: Works in the background without user interaction
Fast Performance: Lightweight and doesn't slow down your site
Easy Integration: Simple setup process with minimal code changes
Reliable: Backed by Cloudflare's global network infrastructure

Prerequisites

Unlike reCAPTCHA and hCAPTCHA, Cloudflare Turnstile requires you to provide your own Site Key and Secret Key from your Cloudflare account.

Important: Provide Your Own Keys

You must provide your own Site Key and Secret Key from your Cloudflare dashboard. Basin does not provide pre-configured keys for Turnstile.

Step 1: Setup Your Cloudflare Account

Create Turnstile Site Keys

Go to the Cloudflare Dashboard
Navigate to Turnstile in the left sidebar
Click Add site to create a new Turnstile site
Configure your site settings:
Site name: Enter a descriptive name for your form
Domain: Add your website domain(s)
Widget mode: Choose your preferred mode (Managed, Non-interactive, or Invisible)
Click Create to generate your Site Key and Secret Key

Cloudflare Documentation

For detailed instructions on setting up Turnstile, see the official Cloudflare Turnstile documentation.

Save Your Keys

After creating your Turnstile site, you'll receive: - Site Key: Used in your HTML form (public) - Secret Key: Used for server-side verification (private)

Keep these keys secure and readily available for the next steps.

Step 2: Add Turnstile Script to Your Page

Add the Cloudflare Turnstile script tag to your page's <head> section, outside of your form code:

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

Insert the Turnstile div within your form using your Site Key from Step 1:

<form accept-charset="UTF-8" action="https://usebasin.com/f/YOUR_FORM_ID" method="POST">
    <input type="text" name="name" placeholder="Your Name" required>
    <input type="email" name="email" placeholder="Your Email" required>
    <textarea name="message" placeholder="Your Message" required></textarea>

    <!-- Cloudflare Turnstile widget -->
    <div class="cf-turnstile" data-sitekey="YOUR_SITE_KEY_HERE"></div>

    <button type="submit">Submit</button>
</form>

Replace YOUR_SITE_KEY_HERE

Make sure to replace YOUR_SITE_KEY_HERE with the actual Site Key from your Cloudflare dashboard.

Step 4: Enable Turnstile in Basin Dashboard

Go to your form's settings: Form → Settings → Spam
Enable "Require valid Turnstile response"
Save your settings

This ensures all form submissions must be accompanied by a successful Turnstile verification.

Complete Example

Here's a complete working example:

<!DOCTYPE html>
<html>
<head>
    <title>Contact Form with Cloudflare Turnstile</title>
    <script src="https://challenges.cloudflare.com/turnstile/v0/api.js?onload=onloadTurnstileCallback" async defer></script>
</head>
<body>
    <form accept-charset="UTF-8" action="https://usebasin.com/f/YOUR_FORM_ID" method="POST">
        <div>
            <label for="name">Name:</label>
            <input type="text" id="name" name="name" required>
        </div>

        <div>
            <label for="email">Email:</label>
            <input type="email" id="email" name="email" required>
        </div>

        <div>
            <label for="message">Message:</label>
            <textarea id="message" name="message" required></textarea>
        </div>

        <!-- Cloudflare Turnstile widget -->
        <div class="cf-turnstile" data-sitekey="YOUR_SITE_KEY_HERE"></div>

        <button type="submit">Send Message</button>
    </form>
</body>
</html>

Advanced Configuration Options

Cloudflare Turnstile offers several configuration options:

Choose the appropriate mode when creating your Turnstile site in the Cloudflare dashboard:

Managed: Automatically chooses between non-interactive and interactive challenges
Non-interactive: Runs completely in the background
Invisible: Hidden widget that activates programmatically

Theme and Size Options

<div class="cf-turnstile" 
     data-sitekey="YOUR_SITE_KEY_HERE"
     data-theme="dark"
     data-size="compact">
</div>

Language Configuration

<div class="cf-turnstile" 
     data-sitekey="YOUR_SITE_KEY_HERE"
     data-language="es">
</div>

Callback Functions

<div class="cf-turnstile" 
     data-sitekey="YOUR_SITE_KEY_HERE"
     data-callback="onTurnstileSuccess"
     data-error-callback="onTurnstileError">
</div>

<script>
function onTurnstileSuccess(token) {
    console.log('Turnstile verification successful');
}

function onTurnstileError(error) {
    console.error('Turnstile verification failed:', error);
}
</script>

Best Practices

User Experience: Turnstile provides the best user experience with minimal friction
Performance: Lightweight and fast, ideal for performance-critical applications
Privacy: Excellent choice for privacy-conscious applications
Reliability: Backed by Cloudflare's robust infrastructure
Testing: Always test in your staging environment before deploying to production

Troubleshooting

Common Issues

Turnstile not loading:
Verify the script is loaded correctly
Check browser console for JavaScript errors
Ensure your Site Key is correct
Widget not displaying:
Confirm your domain is configured correctly in Cloudflare
Check that the Site Key matches your Cloudflare configuration
Verify the widget div is properly formatted
Form submissions blocked:
Ensure Turnstile is enabled in your Basin dashboard
Verify your Secret Key is configured correctly in Cloudflare
Check that the token is being generated and submitted

Debugging Steps

Check Browser Console: Look for JavaScript errors or warnings
Verify Keys: Ensure Site Key and Secret Key are correct
Test Domain: Confirm your domain is properly configured in Cloudflare
Check Network: Verify Turnstile API calls are successful

Domain Configuration

Make sure to add all domains where your form will be used to your Turnstile site configuration in the Cloudflare dashboard:

Production domain (e.g., example.com)
Development domains (e.g., localhost, dev.example.com)
Staging domains (e.g., staging.example.com)

Comparison with Other Solutions

Cloudflare Turnstile is an excellent choice when: - You want the most seamless user experience - Privacy is a top priority - You need reliable, enterprise-grade protection - Performance is critical - You're already using Cloudflare services

For a detailed comparison of all CAPTCHA solutions supported by Basin, see our Comparison Table.

Additional Resources

Support

For additional help with Cloudflare Turnstile implementation, contact Basin support or refer to our comprehensive spam protection documentation.