Stop Bots Without Annoying Your Users: Cloudflare Turnstile for Rails

If you've ever clicked on fire hydrants or traffic lights to prove you're human, you know the frustration of traditional CAPTCHAs. Cloudflare Turnstile offers a privacy-first, often invisible alternative, and now there's a dead-simple way to add it to your Rails app.

Why Turnstile?

Unlike traditional CAPTCHAs, Cloudflare Turnstile:

• Doesn't harvest user data for ad targeting

• Often requires zero interaction from legitimate users

• Works everywhere—no account needed to solve challenges

• Is completely free for unlimited use

Getting Started in 3 Minutes

1. Install the Gem

Add to your Gemfile:

gem 'cloudflare-turnstile-rails'

Then run:

bundle install
rails generate cloudflare_turnstile:install

2. Add Your Keys

Grab your keys from the Cloudflare Dashboard and configure them in config/initializers/cloudflare_turnstile.rb:

Cloudflare::Turnstile::Rails.configure do |config|
  config.site_key   = ENV['CLOUDFLARE_TURNSTILE_SITE_KEY']
  config.secret_key = ENV['CLOUDFLARE_TURNSTILE_SECRET_KEY']
end

3. Add the Widget to Your Form

Drop in a single line:

<%= form_with model: @user do |f| %>
  <%= f.text_field :email %>
  <%= f.password_field :password %>

  <%= cloudflare_turnstile_tag %>

  <%= f.submit "Sign Up" %>
<% end %>

4. Validate in Your Controller

class UsersController < ApplicationController
  def create
    @user = User.new(user_params)

    if valid_turnstile?(model: @user) && @user.save
      redirect_to dashboard_path, notice: "Welcome!"
    else
      render :new, status: :unprocessable_entity
    end
  end
end

That's it! The gem automatically adds validation errors to your model if verification fails.

What Makes This Gem Special?

Works Seamlessly with Hotwire

Using Turbo or Turbo Streams? The widget automatically reinitializes on navigation and stream renders. No JavaScript wiring required.

CSP Compliant Out of the Box

The gem respects Rails' content_security_policy_nonce—no need to allow unsafe-inline in your Content Security Policy.

Full i18n Support

Error messages are translated into 14 languages. Override them easily:

# config/locales/cloudflare_turnstile/en.yml
en:
  cloudflare_turnstile:
    errors:
      default: "Please verify you're human and try again."

Test-Friendly

Cloudflare provides dummy keys for testing. Use them in development and your test suite will pass without any changes:

# Always passes
config.site_key   = '1x00000000000000000000AA'
config.secret_key = '1x0000000000000000000000000000000AA'

Advanced Usage

Need more control? The verify_turnstile method returns a full response object:

result = verify_turnstile(model: @user)

if result.success?
  # Access metadata
  puts result.hostname      # e.g., "example.com"
  puts result.challenge_ts  # e.g., "2025-01-05T12:00:00Z"
  puts result.action        # Custom action name if set
else
  puts result.errors        # ["timeout-or-duplicate"]
end

The Bottom Line

Protecting your Rails forms from bots shouldn't require:

• Wrestling with complex JavaScript

• Compromising user experience

• Leaking data to ad networks

cloudflare-turnstile-rails gives you bot protection in under 10 lines of code, with full support for modern Rails features like Turbo, CSP, and i18n.

---

📦 Install: gem 'cloudflare-turnstile-rails'

🔗 GitHub: github.com/vkononov/cloudflare-turnstile-rails

💎 RubyGems: rubygems.org/gems/cloudflare-turnstile-rails

---

Supports Rails 5.0+ and Ruby 2.6+. MIT Licensed.