Turnstile

Check visitors with Cloudflare Turnstile, so most real people pass without a puzzle.

Puzzles annoy real people. Nobody likes to click on traffic lights. Cloudflare Turnstile checks most visitors in the background. Usually the visitor waits a second and continues. Turnstile asks for a click only when it is not sure.

With this add-on, Turnstile takes the place of the built-in BotBlocker check. Everything else stays the same: the same visitors get a check, and a visitor who passes is let in, as before.

The check comes from Cloudflare, not from your site. The visitor's browser loads it from Cloudflare's servers.

BotBlocker Cloudflare Turnstile settings

The Cloudflare Turnstile panel. Open it from BotBlocker → Add-ons.

Two steps to turn it on

The add-on does nothing until you do both steps:

  1. Save your keys here. In your Cloudflare account, add a Turnstile site. Copy the site key and the secret key into this panel.
  2. Select Turnstile as your check. Go to the CAPTCHA settings and pick Cloudflare Turnstile as the challenge.

Turnstile is grayed out in the CAPTCHA list until both keys are saved. This protects you: BotBlocker never shows a check that nobody can pass.

You do not need to run your site behind Cloudflare. Turnstile works on any site.

What the visitor sees

A suspicious visitor comes to the check page. Now they see the Turnstile box instead of the built-in check. Most of the time, the box shows a short "Verifying" and then a green check mark. The page continues by itself, and BotBlocker lets the visitor in.

When Turnstile is not sure, it asks the visitor to click a checkbox. That is all. There are no picture puzzles.

What goes to Cloudflare

The visitor's browser loads the box from challenges.cloudflare.com. Cloudflare sees that visitor like any other website does.

When the visitor passes, your server asks Cloudflare: "Is this answer real?" It sends the answer, your secret key, and the visitor's IP address. Cloudflare says yes or no. BotBlocker trusts that answer.

If Cloudflare says no, BotBlocker treats it as a wrong answer, the same as in the built-in check. It blocks the visitor's IP address for the Block Time from Blocks and responses.

If Cloudflare cannot check the answer, BotBlocker does not block the visitor. It shows the Button check instead, and the visitor clicks the button to continue. This happens when your server cannot reach Cloudflare, Cloudflare sends a server error, or your secret key is wrong. If Log Manual Verification Requests is on, the log entry for that visit shows CAPTCHA provider error and the reason.

Settings

There are only four settings. You must fill the two keys. The look is up to you.

Cloudflare Turnstile

Site Key

Default: empty

The public key from your Turnstile site in Cloudflare. The browser uses it to show the box. It is not a secret: anyone can see it in the page.

Copy it with no extra spaces. It usually starts with 0x.

Secret Key

Default: empty

The private key. Your server uses it to ask Cloudflare if an answer is real. It never goes to the browser.

Keep it private, like a password. Never put it in a page, a screenshot, or a support message. If someone sees it, make a new one in Cloudflare and paste it here.

Theme

Default: Auto

The color of the box: Light, Dark, or Auto.

Auto follows the visitor's device. If their phone is in dark mode, the box is dark. This is the best choice for most sites. Pick Light or Dark only if your check page always has one fixed color.

Size

Default: Normal

How much space the box takes.

  • Normal: the standard wide box.
  • Flexible: the box stretches to fill the width it has. Good for pages that change size a lot.
  • Compact: a smaller, square box. Good for narrow phone screens.

The size changes only the look. It does not change how strict the check is.

If visitors get stuck

  • You cannot select Turnstile in the CAPTCHA settings? One of the keys is empty. Save both keys here first.
  • Nobody can pass the check? Make sure both keys come from the same Turnstile site. A site key from one site and a secret key from another never work together. Make sure your domain is in the Turnstile site's domain list in Cloudflare.
  • The box does not show at all? Something blocks challenges.cloudflare.com, for example an ad blocker or a strict firewall. Test in a private window with browser extensions turned off.
  • Visitors pass the box, but then see the Button check? Cloudflare could not check the answer. The secret key is wrong, or your server cannot reach Cloudflare. The log entry shows the reason. Check the secret key first. Then ask your host if outgoing connections to challenges.cloudflare.com are allowed.
  • Some visitors must click more often? This is normal on shared networks, VPNs, and privacy browsers. Turnstile is less sure about them. Test from a phone on a mobile network too.
  • You still see the built-in check? Turnstile is not selected in the CAPTCHA settings.
  • You must let visitors in now? Switch the challenge in the CAPTCHA settings back to a built-in check. Your keys stay saved here for later.