TrustCaptcha
Sign inGet started
Ruby on Rails
TrustCaptcha – Bot protection

Ruby on Rails CAPTCHA Integration

Wire TrustCaptcha into a Rails controller — or, even cleaner, into a before_action callback in ApplicationController — in just a few lines of Ruby. Stop bot-driven spam on logins, signups and contact forms without breaking protect_from_forgery or strong params. EU-hosted, GDPR-ready, no image puzzles.

Quickstart

How the integration works

1. Create a CAPTCHA

Create a user account or log in with an existing one. Then create a new CAPTCHA or select an existing one. If you’re unsure whether TrustCaptcha is right for you, try our CAPTCHA service risk-free for 14 days at no cost.

On the CAPTCHA overview page, you will find all the important information, such as the site key and licence key, and you can also create your API key. Allow your websites to access your CAPTCHA by simply adding them to the access authorised domain list in the CAPTCHA security rules.

Start of the CAPTCHA creation form.
CAPTCHA security rules of a demo CAPTCHA.

2. Add the CAPTCHA widget to your ERB template

Drop the TrustCaptcha widget into the ERB template that renders your form. The widget runs the CAPTCHA in the background and adds a hidden tc-verification-token field on submit, which arrives on params like any other input.

app/views/contacts/new.html.erb
HTML
<script type="module" src="https://cdn.trustcomponent.com/trustcaptcha/3.0.x/trustcaptcha.esm.min.js"></script>

<%= form_with url: contact_path, method: :post, local: true do |form| %>
    <%= form.email_field :email, required: true %>
    <trustcaptcha-component sitekey="<your_site_key>"></trustcaptcha-component>
    <%= form.submit "Send" %>
<% end %>

The CAPTCHA widget will then be displayed inside your form:

CAPTCHA done

Need detailed information about the CAPTCHA widget integration?
For the full widget reference — including themes, languages, custom design and more — please read our documentation.

Read the documentation

3. Validate the token in your Rails controller

In your Rails controller, take the verification token from params, look up the result via our Ruby gem, and decide whether to accept the request.

First, install our TrustCaptcha Ruby gem:

Gemfile
Ruby
gem 'trustcaptcha', '~> 3.0'

Then validate the token inside your Rails controller and act on the result:

app/controllers/contacts_controller.rb
Ruby
require 'trustcaptcha/trust_captcha'

class ContactsController < ApplicationController
  def create
    token = params['tc-verification-token'].to_s

    begin
      trust_captcha = TrustCaptcha.new('<your_api_key>')
      result = trust_captcha.get_verification_result(token)
    rescue StandardError
      flash.now[:alert] = 'CAPTCHA verification failed.'
      return render :new, status: :bad_request
    end

    if !result.verification_passed || result.score > 0.5
      flash.now[:alert] = 'CAPTCHA verification failed.'
      return render :new, status: :bad_request
    end

    # CAPTCHA passed — process the request
    redirect_to contact_success_path
  end
end

Need detailed information about the Ruby on Rails CAPTCHA integration?
For full step-by-step instructions — including a reusable before_action callback — please read our documentation.

Read the documentation

Other backend framework instead of Rails?
If you use a different framework, pick the matching recipe here. If your framework isn’t listed, your software developers can integrate the verification themselves using our documentation or ask our support team for a pre-built integration.

Actix Web
ASP.NET Core
Axum
Django
Echo
Express
FastAPI
Fastify
Fiber
Flask
Gin
Hapi
Laravel
Micronaut
NestJS
Next.js
Quarkus
Ruby on Rails
Sinatra
Spring Boot
Symfony

4. Congratulations 🎉

You are now protected by TrustCaptcha - congratulations!

CAPTCHA done

FAQs

Where in a Rails app does the CAPTCHA verification go?
Inside the controller action that receives the form submission, before persisting the model or sending the email. The CAPTCHA token comes in as a regular form field on params (default name: "tc-verification-token").
Can I run the verification as a before_action callback?
Yes — and that's the cleanest way once you protect more than one action. Define a private verify_trust_captcha method in ApplicationController (or a Concern) that calls our Ruby gem and uses head :bad_request on failure. Then add before_action :verify_trust_captcha, only: :create to any controller.
Does TrustCaptcha replace Rails' protect_from_forgery (CSRF)?
No. Rails CSRF protection and TrustCaptcha are independent layers — both should stay enabled. The CAPTCHA token only confirms that a human filled the form, it does not protect against cross-site request forgery.
Do I need to permit the token field in strong params?
No. The CAPTCHA token is read from params directly (params['tc-verification-token']), not via the model's strong-params hash. Your existing model_params method stays unchanged.
Where should I store the CAPTCHA API key in a Rails app?
Use Rails encrypted credentials (rails credentials:edit) and read the key with Rails.application.credentials.trustcaptcha[:api_key]. Build a single TrustCaptcha instance once in config/initializers/trustcaptcha.rb to reuse across requests.
Losing leads to CAPTCHAs?

TrustCaptcha blocks spam and bots, not customers. No puzzles, GDPR-ready, EU-hosted.

CAPTCHA start
CAPTCHA done
Puzzle-free UX
Runs in the background while visitors type — so more people finish your forms and fewer drop off.
GDPR-ready
EU-hosted and privacy-first: no cookies, encrypted transmission, automatic cleanup — with ready-to-use legal resources.
Multi-layer Security
Adaptive protection plus intelligent risk scoring stops abuse early — even when attack traffic spikes.
Full Control
Fine-tune sensitivity, set allow/block lists, and use geoblocking — you decide how strict verification should be.

Protect your Ruby on Rails application with TrustCaptcha in just a few steps!

  • EU-hosted & GDPR-ready
  • No puzzles
  • Try free for 14 days
Get started Contact sales