Self-hosted file hosting
Sign up

Main

How to Set Up reCAPTCHA v3 for XFile Ultra

Create a Google reCAPTCHA v3 score-based key, paste site and secret keys into Captcha & abuse, and optionally tune RECAPTCHA_V3_MIN_SCORE.

How to Set Up reCAPTCHA v3 for XFile Ultra

reCAPTCHA v3 is mostly invisible. Google returns a risk score when someone submits a protected form; XFile Ultra accepts or rejects based on a minimum score. There is no “I'm not a robot” checkbox in normal use.

You need a v3 key pair from Google. A v2 key will not work in v3 mode.

Where to find it in XFile Ultra

Admin → Settings → Settings (first / Main tab) → Captcha & abuse

1. Set Provider to reCAPTCHA v3

2. Paste reCAPTCHA v3 site key and reCAPTCHA v3 secret key

3. Under Captcha on forms, enable the surfaces you want

4. Save settings

5. Optional: set RECAPTCHA_V3_MIN_SCORE on the server if you need a stricter or looser floor (default 0.5)

Fields in XFile Ultra

Field in admin Setting key From Google
reCAPTCHA v3 site key recaptcha3_pub_key Site key
reCAPTCHA v3 secret key recaptcha3_pri_key Secret key

Env fallbacks: NEXT_PUBLIC_RECAPTCHA_V3_SITE_KEY and RECAPTCHA_V3_SECRET_KEY.

Score threshold (not in the admin UI)

There is no slider in Settings for the minimum score. The server uses:

RECAPTCHA_V3_MIN_SCORE=0.5
  • Default if unset: 0.5
  • Lower (example 0.3) → fewer false blocks, more bots may pass
  • Higher (example 0.7) → stricter, more real users may fail

Set it in the app environment on the VPS, then restart the app process.

Step 1 — Create a v3 key in Google

1. Open the Google reCAPTCHA admin

2. Sign in with a Google account

3. Register a new site

4. Label: example example.com — v3

5. reCAPTCHA type: reCAPTCHA v3 (score based)

6. Domains: add example.com, and www.example.com / localhost if needed (no https://)

7. Accept terms and submit

8. Copy Site key and Secret key

Do not reuse a v2 checkbox key here.

Step 2 — Paste keys into XFile Ultra

1. Go to Admin → Settings → Settings (first / Main tab) → Captcha & abuse

2. Provider → reCAPTCHA v3

3. Paste Site key → reCAPTCHA v3 site key

4. Paste Secret key → reCAPTCHA v3 secret key

5. Enable the forms you want under Captcha on forms

6. Save settings

Step 3 — Verify it works

1. Open a protected form in a normal browser (example: /contact)

2. You should not see a checkbox; the page may show a small reCAPTCHA badge / “Protected by reCAPTCHA v3” style notice

3. Submit a valid form — it should succeed for a normal browser session

4. If legitimate users are blocked often, lower RECAPTCHA_V3_MIN_SCORE and restart

Domains checklist

Same rules as v2: list every public hostname you use. Domain changes can take a few minutes.

Common problems

Invalid site key / always fails

You pasted a v2 key into v3 fields, or mixed site/secret from different keys. Create a dedicated v3 site in Google.

Real users blocked as bots

Score floor too high, aggressive traffic filters, or shared/VPN IPs scoring low. Lower RECAPTCHA_V3_MIN_SCORE slightly, or switch to reCAPTCHA v2 if you prefer an explicit challenge.

No captcha UI — is it broken?

v3 is invisible by design. Check that Provider is reCAPTCHA v3, keys are filled, and the form toggle is on. Failed submits with captcha errors mean verification ran.

Secret blank after save

Expected. Leave empty to keep the stored secret.

Related