TrustCaptcha · Bot protection

Ruby CAPTCHA Integration

Add a Ruby CAPTCHA to your Ruby or Rails backend to protect sign-ups, logins, contact forms and checkouts from bots. This guide shows the setup and how to validate requests with our ready-made Ruby gem. EU-hosted, GDPR-compliant and without puzzles for your visitors.

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 pick an existing one. If you want to try TrustCaptcha first, every plan comes with a 14-day free trial.

The CAPTCHA overview page shows your site key and license key, and you create your API key there. Add your website’s domains to the authorized domains in the CAPTCHA security rules so they can use your CAPTCHA.

CAPTCHA security rules of a demo CAPTCHA.

2. Integrate the CAPTCHA widget into your frontend

Integrate the CAPTCHA widget into your website or app. The CAPTCHA widget guide in our documentation has step-by-step instructions.

Read the documentation

The CAPTCHA widget will then be displayed on your website or app:

Pre-built frontend integrations
Our pre-built frontend integrations add the CAPTCHA widget to your website or application. If there is none for your frontend technology yet, your developers can integrate the widget themselves using our documentation or ask our support team for a pre-built integration.

3. Validate the CAPTCHA result in your backend

The following steps show how a Ruby backend fetches the CAPTCHA verification result from our server and decides what to do with it. For the full instructions, read the CAPTCHA integration guide for Ruby in our documentation.

Read the documentation

First, install our TrustCaptcha Ruby dependency:

Install

bash

gem install trustcaptcha

Fetch the verification result from our server with the verification token and your API key:

Fetch Result

Ruby

# Retrieving the verification result
begin
  trust_captcha = TrustCaptcha.new('<your_api_key>')
  verification_result = trust_captcha.get_verification_result('<verification_token_from_your_client>')
rescue StandardError => e
  # Fetch verification result failed - handle error
end

Based on the verification result and your own requirements, decide how to proceed:

Handle Result

Ruby

# Act on the verification result
if !verification_result.verification_passed || verification_result.score > 0.5
  # Verification failed or bot score > 0.5 - possible automated request
end

Need detailed information about the Ruby CAPTCHA integration?
Our Ruby CAPTCHA integration guide has the detailed instructions, and our CAPTCHA samples repository on GitHub has a complete integration example.

Other backend technology instead of Ruby?
If you run something other than Ruby on your server, or have several backends, pick a different integration here. If we have no pre-built integration for your backend technology yet, your developers can integrate the CAPTCHA verification themselves using our documentation or ask our support team for a pre-built integration.

4. Test your integration

TrustCaptcha is now active. Send a test request and check that it goes through.

FAQs

How does a Ruby CAPTCHA check work?

A Ruby CAPTCHA is a check your app runs before it processes a form. The widget in your frontend solves a proof-of-work task in the background while our servers calculate a bot score from the signals it sends, then adds a verification token to your form. Your Ruby code creates a client with TrustCaptcha.new(api_key) and calls get_verification_result with that token. You get whether the verification passed and a bot score from 0 (very likely human) to 1 (very likely bot), so this bot detection keeps spam, credential stuffing and scraping out of your forms without a puzzle.

Can I use the gem in Rails, Sinatra or a plain Rack app?

Yes. The trustcaptcha gem only makes the server-side call, so it works in Rails controllers, Sinatra routes and any Rack app. Read the token from params['tc-verification-token'], fetch the result before you save anything and return an error if the check fails. Our Rails and Sinatra guides show the code for each framework.

Where should I keep the API key in a Ruby app?

Keep it out of your repository. In Rails, store it in the encrypted credentials or an environment variable; in Sinatra or Rack apps, read it from ENV. Then pass it to TrustCaptcha.new. The constructor also takes api_host, connect_timeout_s (3 seconds by default), read_timeout_s (5 seconds by default) and proxy if you need them.

Which exceptions does the gem raise?

get_verification_result raises typed exceptions such as TrustCaptcha::VerificationTokenInvalidException, TrustCaptcha::VerificationResultExpiredException or TrustCaptcha::VerificationResultRetrievalLimitReachedException; treat those as a failed check. TrustCaptcha::ServerUnreachableException means your server could not reach our API at all, and our documentation suggests allowing the request and logging the incident. TrustCaptcha::ClientReportedServerUnreachableException means the widget reported an outage your server cannot confirm, so reject the request or ask for another check.

Is TrustCaptcha GDPR-compliant?

All verification data is processed and stored exclusively in the EU on ISO 27001-certified infrastructure, no cookies are set and you can sign the Data Processing Agreement online. Whether your use is compliant depends on your setup and your privacy policy. This is not legal advice; check the details with your data protection officer.

Will TrustCaptcha slow my Ruby app?

The gem makes one HTTPS request per submitted form to fetch the verification result, so your Ruby app does little extra work. The proof-of-work runs in the visitor's browser in the background, and there are no puzzle images to download.

Can I style TrustCaptcha to match my brand?

Yes. You can switch between light and dark themes or follow the system setting, use 37+ languages ready to use, add any other language and override every widget text. From the Team plan you can change colors, borders and corner radius. Hiding our branding or running the widget fully invisible is the paid Captcha Branding add-on.

Losing leads to CAPTCHAs?

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

No puzzles for visitors

The check runs in the background while visitors type, so more people finish your forms instead of giving up.

GDPR-compliant

Hosted in the EU, no cookies, encrypted transmission and automatic data deletion. Every customer gets a Data Processing Agreement.

Multi-layer security

Adaptive proof-of-work and risk scoring stop abuse early, even when attack traffic spikes.

Full control

Set the sensitivity, keep allow and block lists and use geoblocking. You decide how strict the check is.

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

EU-hosted & GDPR-compliant
No puzzles
Try free for 14 days

Get started Contact sales