Gravity Forms Turnstile Premium Add-on Setup Guide

The Gravity Forms Turnstile Premium Add-on puts a Cloudflare Turnstile captcha on your Gravity Forms and checks the answer on your own server before an entry is saved. It is a spam and bot captcha, the same job as a checkbox captcha, only quieter: most real visitors tick nothing and see nothing, while scripts and bots are stopped at the door. When a submission has no Turnstile answer, or a wrong, expired or already-used one, the entry is blocked and never reaches your database or your notifications.

Everything is verified where it matters, on the server. The visitor’s browser gets a token from Cloudflare, your site sends that token to Cloudflare to confirm it is genuine, and only a confirmed token lets the form through. The one outside service the add-on ever contacts is Cloudflare, and your secret key is kept encrypted on your site.

What you need

• WordPress with Gravity Forms 2.9 or newer.
• PHP 7.4 or newer.
• An active license key for this add-on.
• A free Cloudflare account, to make a Turnstile widget and get its two keys.

If Gravity Forms is missing or older than 2.9, the add-on shows a notice in the WordPress admin and does nothing else, so a form is never left half protected.

Get your Cloudflare keys

Turnstile is a free Cloudflare product. Sign in to the Cloudflare dashboard, open the Turnstile section and add a new widget. Give it a name you will recognise, add the domain of your site, and choose a widget mode. Managed is the usual choice and lets Cloudflare decide when to challenge; you can also pick invisible. Cloudflare then gives you two values: a site key, which is public and goes into the page, and a secret key, which is private and is used only on your server to verify the answer. Copy both. You will paste them into the add-on settings in a moment.

The site key and the secret key belong together. If you ever rotate them in Cloudflare, update both here at the same time, or verification will fail and submissions will be stopped.

The settings page

Install and activate the add-on like any plugin, after Gravity Forms. Then open Forms → Settings → Turnstile. This one page holds the license key, your Cloudflare keys and the way the captcha behaves across your site.

Your keys and the test button

Paste the site key and the secret key from Cloudflare. The secret key is stored encrypted at rest, so the plain value is never left sitting in the database. After the field is saved it is shown masked, and you can replace it at any time.

Next to the keys is a test key button. Press it and the add-on asks Cloudflare whether your pair of keys is accepted. A green result means the keys talk to Cloudflare and verification will work; a clear message tells you if a key is wrong or the domain does not match. Run the test once whenever you paste new keys, so you learn about a typo here and not from a visitor who cannot submit.

Protect all forms

You have two ways to put Turnstile on a form. The quick way is the Protect all forms option on this page. Turn it on and every form on the site is covered, with the captcha added automatically before the submit button, using the default look you set below. You do not have to touch each form. This is the fastest way to stop a sudden wave of spam.

The other way is per form, by adding a Turnstile field in the form editor, which is covered further down. Use the field when you want to place the captcha exactly, or protect only some forms. A form with its own field uses that field; the global option covers the rest.

Fail mode and timeout

Verification talks to Cloudflare over the network, and once in a while a network call is slow or Cloudflare is briefly unreachable. The fail mode decides what happens then.

• Fail closed is the safe default. If the answer cannot be verified, the submission is blocked. Nothing gets through unchecked, which is what you want for a captcha whose job is to keep bots out.
• Fail open lets a submission through when the check itself could not be completed in time. Choose this only when it matters more that no genuine visitor is ever turned away than that every bot is caught.

The verify timeout sets how long the server waits for Cloudflare before it gives up and applies the fail mode. A few seconds is plenty. A valid, wrong, expired or reused answer is decided immediately; the timeout only matters when the network itself is the problem.

Default look and language

The last part of the page sets the defaults used by the global option and by any new field: the theme, which can be auto, light or dark; the size, which can be normal, flexible or compact; and the language, which can follow the visitor’s browser or be fixed to one you choose. Auto theme follows the visitor’s system setting, so the widget sits well on both a light and a dark page. Each field can override these, so the defaults are just a sensible starting point.

Add the Turnstile field

For precise placement, open a form in the editor and add the Turnstile field from the field list. Drop it where you want the captcha to appear, usually just above the submit button. Because it is a real field, you can give it a label, place it in a particular column, and set its own theme, size and language if the form needs something different from the site default.

A form needs only one Turnstile field. If you add the field to a form, that field is what protects it, whether or not the global option is on. One captcha per form is the right amount: it checks every submission once.

Managed and invisible modes

Turnstile runs in one of two modes, and you choose per field or in the defaults.

Managed mode shows a small widget, and Cloudflare decides whether a visitor needs to do anything. Most people see a brief check and a tick, with no puzzle to solve. If a visitor looks risky, Cloudflare may ask for a simple interaction. This is the mode most sites want, because it is visible enough that people trust it and quiet enough that it rarely gets in the way.

Invisible mode shows nothing at all. The check runs in the background and the token is gathered when the visitor presses submit. There is no widget to see, which keeps a clean form clean, while the server still verifies the token exactly as before. Pick invisible when you do not want any visible element but still want every submission checked.

What happens on submit

When a visitor sends the form, their browser already holds a Turnstile token. Your site posts that token, together with your secret key, to the Cloudflare siteverify endpoint. Cloudflare answers whether the token is genuine, and the add-on acts on the answer before Gravity Forms saves anything.

A good answer lets the entry save and the notifications send as normal. A missing token, a wrong one, an expired one or one that has already been used is rejected, the visitor sees a clear message asking them to complete the check again, and no entry is written. Because a token can be used only once, a bot cannot capture a single good token and replay it across many submissions.

The result on the entry

Every entry keeps a small Turnstile result, so you can see how a submission was treated. It reads as passed when the token was verified, or not checked when the form was not protected at the time or the add-on had no license. It is a quiet record in the entry detail, handy when you are tuning a form or confirming that protection is live.

AJAX, multi-page and save-and-continue

The add-on is built for the ways Gravity Forms is really used. On an AJAX form, where the page does not reload on submit, the widget resets itself after a submission so the next attempt gets a fresh token. On a multi-page form the captcha is handled at the final step, so a visitor is not asked to prove themselves on page one and again on page three; the token is gathered and verified when the whole form is sent. Save and continue works too: a visitor can save a draft and come back, and the check is applied when they finally submit, not when they pause.

In every case the rule is the same. The server verifies a genuine, unused token before the entry is saved. The different flows only change when the token is collected, never whether it is checked.

Privacy and security

The only outside service the add-on talks to is Cloudflare, and only to verify a token. It sends the token and your secret key to the Cloudflare siteverify address and reads back whether the token is valid. It does not call any other service and does not add tracking of its own.

Your secret key is encrypted at rest on your site, so it is not stored as plain text. The site key is public by design and lives in the page, as every captcha site key does. Verification happens on your server, which means a visitor cannot fake a pass by editing the page; the final word always comes from Cloudflare through your own server.

Troubleshooting

• Every submission is blocked: run the test key button. A wrong secret key, or a domain in Cloudflare that does not match your site, is the usual cause.
• No widget shows in managed mode: check that the site key is set and that the form has either a Turnstile field or the global option on.
• Genuine visitors are turned away during an outage: if that is a worse problem than letting a few bots through, switch the fail mode to fail open and give the timeout a little more room.
• The widget looks wrong on a dark page: set the theme to auto, or fix it to dark for that form.

Questions

Do I need a paid Cloudflare plan?

No. Turnstile is free, and you only need a Cloudflare account to make a widget and copy its two keys.

Can I protect just one form?

Yes. Leave the global option off and add a Turnstile field to the one form you want to cover.

Is my secret key safe?

Yes. It is stored encrypted and is used only on your server to verify tokens with Cloudflare. It is never shown in the page.

Will a bot be able to reuse a captcha answer?

No. A token can be verified only once, so a captured answer cannot be replayed on another submission.

Which Gravity Forms versions are supported?

Gravity Forms 2.9 and newer, on PHP 7.4 and newer.