Bot protection uses Cloudflare Turnstile, a privacy-friendly challenge that usually passes real visitors without a puzzle. dply can create the Turnstile keys for your app, add the widget to your HTML forms, and check tokens at the edge for Forms and Rate limits.
Note
Bot protection needs dply-hosted delivery, which is the default.
Turn on bot protection
- Open your app and choose Bot protection.
- Tick Bot protection is on. If the app has no keys yet, dply creates a Turnstile widget for your app's hostnames, saves its keys, and turns protection on.
- Click Check visitors on form posts only to choose where to check: Form posts only (recommended) or Every page. Choose Save in the dialog.
The page opens with a sentence such as "Visitors are checked on your forms. Your /contact form and /login rate limit rely on it." Under Also uses it, each form that requires a bot check and each rate-limit rule that challenges is listed, with a link to its page.
The widget appears on matching pages within about a minute.
Use your own keys
To use keys from your own Cloudflare account, create a Turnstile widget in the Cloudflare dashboard, then open Keys, paste its Site key (public) and Secret key, choose Save, and tick Bot protection is on.
The site key is public and safe in HTML. The secret key is used only at the edge to verify tokens. Don't put it in your frontend code. Only members who can edit the app can see the secret key on this page.
Regenerate keys
Open Keys and choose Regenerate. You're asked to confirm, then dply creates a new widget and replaces both keys.
Important
Generated keys are tied to the hostnames and domains your app had when you generated them. If you later attach a custom domain on a domain the app didn't use before, open Keys and choose Regenerate so the widget accepts it.
What each mode does
When the mode applies, dply adds the Turnstile script to your static HTML pages, and inserts the widget immediately before the first </form> on any page that doesn't already have one.
| Mode | When it applies |
|---|---|
| Form posts only | Only while Forms is enabled for the app. |
| Every page | Always, whether or not Forms is enabled. |
Neither mode blocks page views on its own. A token is only checked where something asks for it:
- Forms endpoints with Require bot check reject submissions without a valid token.
- Rate limits with Challenge (bot check) show a Turnstile page to visitors over the limit.
- Your own server code can verify the token with Turnstile's API.
Note
The widget is added to static HTML served from your deploy. For SSR and container apps, and for hybrid origin responses, add the widget to your templates yourself, using the site key from this page:
<div class="cf-turnstile" data-sitekey="YOUR_SITE_KEY"></div>
<script src="https://challenges.cloudflare.com/turnstile/v0/api.js" async defer></script>
Checking tokens
When the widget completes, it adds a hidden cf-turnstile-response field to the form. dply's edge checks that token against Turnstile, along with the visitor's IP:
- Forms read
cf-turnstile-responseorturnstile_tokenfrom the form body or JSON. - Rate limit challenges read the
cf-turnstile-responseheader or query parameter.