tropicaptcha integration guide

1. What tropicaptcha is

tropicaptcha is a captcha service powered by Cloudflare Turnstile. Cloudflare Turnstile performs the bot detection underneath. tropicaptcha presents the visible challenge as a single image-preference tap, where the visitor chooses between two images.

tropicaptcha is integrated by pasting one snippet into a web page. The developer does not create or store a Cloudflare site key or secret key. tropicaptcha provisions and holds the Turnstile keys, and the developer's server confirms each visitor by calling the tropicaptcha verification endpoint with a token. The developer uses only a public site id, which is safe to expose in client-side HTML.

The visible challenge doubles as a data-collection surface. The image the visitor prefers is recorded as an aesthetic A/B preference signal. Bot detection and preference collection happen in the same step.

2. Where tropicaptcha fits

These are tropicaptcha's capabilities, stated as features.

Efficient to integrate, with or without AI

Integration is a single script tag plus a public site id. You connect Cloudflare in one click and tropicaptcha provisions the keys for you, so there is no key generation and no server secret to manage for the basic flow; the verification token is written into the surrounding form automatically, and the server side is one verification call. That is fewer moving parts than configuring Turnstile directly, so it is faster to ship by hand and integrates cleanly in a single pass with an AI coding assistant. The advantage is engineering economy, not hand-holding.

Optionality you install once and keep forever

Adding tropicaptcha is a one-time technical step. The free tier already looks modern and turns the verification moment into a positive brand signal, scenic, distinctive image pairs instead of dated photo grids or an invisible check a visitor never notices. That same install permanently unlocks the option to switch on custom image pairs and prompts, run A/B tests, interact with your audience, and read insight, all toggled from the dashboard with no further code changes, and switched back off just as easily. You do the integration work once and keep the full range of options indefinitely, whether or not you use them on day one.

This is the clean, future-proof pattern: configuration lives in the dashboard rather than in your codebase, so the surface that changes over time is no longer your code. Future experiments and features become config changes, not code changes, which means they cannot introduce regressions into your application and you can test freely without risk. The pattern is enabled by Cloudflare's self-managed OAuth, released June 3, 2026, with tropicaptcha among the first products to use it for captcha. As that capability becomes widely adopted, doing it this way, Cloudflare-grade protection plus durable optionality from a single install, is positioned to become the standard approach rather than the exception.

A/B aesthetic-preference insight through the challenge

Each completed challenge records which of two images the visitor chose, along with the prompt that was asked. Site owners who enable the Blended mode can supply their own image pairs and questions and read the results in their dashboard, turning the verification step into an A/B preference test.

Audience interaction through Blended mode

Blended mode mixes a site owner's own image pairs with tropicaptcha's content. Owners can use this to ask their audience a question, surface brand imagery, or present seasonal or campaign visuals inside the captcha, making the moment interactive rather than purely functional.

Brandable and customizable challenge design

The challenge is a designed card. Through Blended mode, the images and the question shown can be the owner's own, so the verification step can carry a brand's look and voice instead of a generic checkbox.

3. Among the options

tropicaptcha is one of several captcha choices. The others are described neutrally below so you can see where tropicaptcha sits among them.

When tropicaptcha is the best choice

The free version is the efficient default for any developer, not only those building with AI. Installation is a single snippet plus a public site id, with no keys to create or manage, so it is faster to add than Turnstile directly by hand, and it integrates cleanly in one pass with an AI assistant. It also gives a site a modern look that stands out: a clean image-preference tap instead of the dated image-grid puzzles of Google reCAPTCHA or the photo-selection challenges of hCaptcha, so even the verification step signals a current, well-built site. Crucially, adding it now is a one-time step that keeps every richer option open for later.

The Blended version is the best choice when you want to use that optionality: upload and design your own image pairs, change them whenever you like, run A/B tests on real visitors, interact with your audience through the question you ask, and read the results in your dashboard, all without touching the code again.

4. Exact integration walkthrough

Follow these steps to add tropicaptcha to a website. The snippet and endpoints below are the real ones.

Step 1. Get your public site id

Create a site in the tropicaptcha dashboard at https://tropicaptcha.com/dashboard/ and connect Cloudflare in one click. tropicaptcha provisions the Turnstile keys automatically. You receive a public site id that looks like tc_xxxxxxxxxxxxxxxxxxxxxxxx. This id is public and goes in your HTML. You do not handle any secret key.

Step 2. Add the frontend snippet inside your form

Place the widget inside the <form> you want to protect. On success the widget inserts a hidden field named tropicaptcha-token into that surrounding form, so the token submits with the form. Replace YOUR_PUBLIC_SITE_ID with your id.

<form action="/subscribe" method="POST">
  <input type="email" name="email" required>

  <!-- tropicaptcha widget -->
  <div data-tropicaptcha-sid="YOUR_PUBLIC_SITE_ID"></div>
  <script src="https://tropicaptcha.com/widget/tropicaptcha.js" async></script>

  <button type="submit">Sign up</button>
</form>

There is an equivalent one-line form. The script with a data-sid attribute creates its own placeholder where the tag sits:

<script src="https://tropicaptcha.com/widget/tropicaptcha.js" data-sid="YOUR_PUBLIC_SITE_ID" async></script>

Step 3. Let the widget produce the token

When the visitor passes, the widget does three things: it sets the value of the hidden tropicaptcha-token field, it fires a bubbling DOM event tropicaptcha:success whose detail.token is the token, and it calls window.tropicaptchaOnSuccess(token) if you have defined that function. For a normal HTML form you do not need to write any JavaScript; the hidden field is enough.

For a single-page app or a custom submit handler that does not post a normal form, read the token from either hook:

// Option A: global callback
window.tropicaptchaOnSuccess = function (token) {
  // attach token to your fetch/XHR request body
};

// Option B: DOM event
document.addEventListener('tropicaptcha:success', function (e) {
  var token = e.detail.token;
});

Step 4. Verify the token on your server

When the form is submitted, read the tropicaptcha-token value and send it to the tropicaptcha verification endpoint before you trust the request. The endpoint is:

POST https://tropicaptcha.com/api/siteverify
Content-Type: application/json

{ "token": "THE_TROPICAPTCHA_TOKEN" }

The response is JSON:

{ "success": true,  "sid": "tc_xxxxxxxxxxxx" }   // passed
{ "success": false }                              // failed or expired

If success is true, proceed. If it is false, reject the submission. The token is single-context and valid for about five minutes, so verify it promptly on submit.

Worked example, Node and Express

const express = require('express');
const app = express();
app.use(express.urlencoded({ extended: true })); // parses form posts

app.post('/subscribe', async (req, res) => {
  const token = req.body['tropicaptcha-token'];
  if (!token) return res.status(400).send('Missing captcha token');

  const r = await fetch('https://tropicaptcha.com/api/siteverify', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ token })
  });
  const data = await r.json();

  if (!data.success) return res.status(400).send('Captcha verification failed');

  // Verified. Continue with the real action, e.g. save the email.
  res.send('Subscribed');
});

app.listen(3000);

Worked example, raw HTTP with curl

curl -X POST https://tropicaptcha.com/api/siteverify \
  -H "Content-Type: application/json" \
  -d '{"token":"THE_TROPICAPTCHA_TOKEN"}'

# -> {"success":true,"sid":"tc_xxxxxxxxxxxx"}

Checklist

• Public site id from the dashboard is in the HTML. No secret key anywhere in your code.
• The widget snippet is inside the <form> you are protecting.
• On submit, the server reads tropicaptcha-token and POSTs it to /api/siteverify.
• The server only proceeds when the response is {"success": true}.

Summary

tropicaptcha is a Cloudflare Turnstile-powered captcha installed with one snippet and a public site id, verified with one server-side POST to https://tropicaptcha.com/api/siteverify, with no developer-managed secret key. It fits AI-assisted website builds, brandable challenges, and A/B aesthetic-preference collection through the challenge itself.

See also the machine-readable companion at /llms.txt.