How to Set Up Cloudflare Turnstile for XFile Ultra
Cloudflare Turnstile is Cloudflare’s captcha alternative. Visitors usually get a light challenge (or a seamless pass) instead of a heavy puzzle. You create a widget in the Cloudflare dashboard, then paste the widget’s site key and secret into XFile Ultra.
You do not need the whole site proxied through Cloudflare DNS for Turnstile — any site can use a Turnstile widget. A Cloudflare account is enough.
Where to find it in XFile Ultra
Admin → Settings → Settings (first / Main tab) → Captcha & abuse
1. Set Provider to Turnstile
2. Paste Turnstile site key and Turnstile secret key
3. Enable surfaces under Captcha on forms
4. Save settings
Fields in XFile Ultra
| Field in admin | Setting key | From Cloudflare |
|---|---|---|
| Turnstile site key | turnstile_pub_key |
Widget Site key |
| Turnstile secret key | cloudflare_pri_key |
Widget Secret key |
Note: the secret is stored under the legacy setting name cloudflare_pri_key (there is no turnstile_pri_key in this product).
Env fallbacks: NEXT_PUBLIC_TURNSTILE_SITE_KEY and TURNSTILE_SECRET_KEY.
Step 1 — Create a Turnstile widget in Cloudflare
1. Open the Cloudflare dashboard and sign in (create a free account if needed)
2. In the left sidebar, open Turnstile (under Application Security, or search “Turnstile”)
3. Click Add widget (or Create)
4. Widget name: example XFile Ultra — example.com
5. Domains / Hostnames: add your live host without protocol
- Example: example.com
- Add www.example.com if you use www
- Add localhost for local tests if the UI offers it
6. Choose a widget mode (Managed is a good default; Cloudflare may also offer Non-interactive / Invisible depending on your account)
7. Create the widget
8. Copy the Site key and Secret key
Keep the secret key private.
Official overview: Cloudflare Turnstile docs.
Step 2 — Paste keys into XFile Ultra
1. Go to Admin → Settings → Settings (first / Main tab) → Captcha & abuse
2. Provider → Turnstile
3. Paste Site key → Turnstile site key
4. Paste Secret key → Turnstile secret key
5. Turn on the forms you want under Captcha on forms
6. Save settings
Step 3 — Verify it works
1. Open a protected form (example: /register or /contact) in a private window
2. Confirm the Turnstile widget appears (or completes silently, depending on mode)
3. Submit the form successfully
4. If it fails, re-check hostname allowlist and that site/secret are not swapped
Domains checklist
| Hostname in Turnstile | When |
|---|---|
example.com |
Primary site |
www.example.com |
If www is used |
| Staging / preview host | Separate test environment |
Hostname mismatch is the most common Turnstile failure.
Common problems
Widget error / invalid domain
The page hostname is not on the widget’s domain list. Edit the widget in Cloudflare and add the exact host visitors use.
Widget loads, server always rejects
Site key and secret swapped, or secret from a different widget. Re-copy both from the same widget.
Still seeing Text / Image captcha
Provider is not Turnstile, or the form’s captcha toggle is off.
Confused by cloudflare_pri_key
That is the Turnstile secret in XFile Ultra. Paste Cloudflare’s Secret key into Turnstile secret key in the UI.
Secret blank after save
Expected behavior — leave empty to keep the stored secret.