Skip to main content
XyraPanel includes built-in captcha support to protect authentication endpoints from bots and automated attacks. Three providers are supported: Cloudflare Turnstile, Google reCAPTCHA, and hCaptcha.

​
Provider Selection

​
CAPTCHA_PROVIDER
string
required
Choose your captcha provider:
  • turnstile - Cloudflare Turnstile (recommended)
  • recaptcha - Google reCAPTCHA v3
  • hcaptcha - hCaptcha
CAPTCHA_PROVIDER="turnstile"
Only configure environment variables for your chosen provider. You don’t need to set up all three.
Turnstile is Cloudflare’s privacy-focused alternative to reCAPTCHA with better user experience and no Google dependencies.

​
Why Turnstile?

  • Privacy-focused: No tracking or data collection
  • Better UX: Most users never see a challenge
  • Free: No limits for most use cases
  • Fast: Leverages Cloudflare’s global network

​
Configuration

​
NUXT_TURNSTILE_SECRET_KEY
string
required
Turnstile secret key from Cloudflare dashboard.
NUXT_TURNSTILE_SECRET_KEY="0x4AAA..."
​
NUXT_PUBLIC_TURNSTILE_SITE_KEY
string
required
Turnstile site key (public) from Cloudflare dashboard.
NUXT_PUBLIC_TURNSTILE_SITE_KEY="0x4BBB..."
Test mode key:
NUXT_PUBLIC_TURNSTILE_SITE_KEY="1x00000000000000000000AA"
The test mode key always passes verification. Use only in development!

​
Setup Instructions

1

Create Turnstile site

  1. Log in to Cloudflare Dashboard
  2. Navigate to Turnstile in the sidebar
  3. Click Add Site
  4. Enter your domain (e.g., panel.example.com)
  5. Choose widget mode: Managed (recommended)
2

Get your keys

After creating the site, copy:
  • Site Key (public, used in frontend)
  • Secret Key (private, used in backend)
3

Configure environment

Add to your .env file:
CAPTCHA_PROVIDER="turnstile"
NUXT_TURNSTILE_SECRET_KEY="your-secret-key"
NUXT_PUBLIC_TURNSTILE_SITE_KEY="your-site-key"
4

Restart application

Restart XyraPanel to apply the new configuration.

​
Google reCAPTCHA v3

reCAPTCHA v3 provides invisible bot protection using risk analysis.

​
Configuration

​
NUXT_RECAPTCHA_SECRET_KEY
string
required
reCAPTCHA secret key from Google.
NUXT_RECAPTCHA_SECRET_KEY="6LcXXX..."
​
NUXT_RECAPTCHA_MIN_SCORE
number
default:"0.5"
Minimum score required to pass verification (0.0 to 1.0).
  • 0.0 - Most lenient (may allow bots)
  • 0.5 - Balanced (recommended)
  • 1.0 - Strictest (may block legitimate users)
NUXT_RECAPTCHA_MIN_SCORE="0.5"

​
Setup Instructions

1

Create reCAPTCHA site

  1. Go to Google reCAPTCHA Admin
  2. Click + to create a new site
  3. Enter:
    • Label: Your panel name
    • reCAPTCHA type: reCAPTCHA v3
    • Domains: Your domain (e.g., panel.example.com)
  4. Accept terms and submit
2

Get your keys

After creating the site, copy:
  • Site Key (public)
  • Secret Key (private)
3

Configure environment

Add to your .env file:
CAPTCHA_PROVIDER="recaptcha"
NUXT_RECAPTCHA_SECRET_KEY="your-secret-key"
NUXT_RECAPTCHA_MIN_SCORE="0.5"
4

Restart application

Restart XyraPanel to apply the new configuration.

​
Adjusting Min Score

If you receive complaints about false positives:
  • Lower score (0.3-0.4): More lenient, fewer false positives, slight security reduction
  • Higher score (0.6-0.7): Stricter protection, more false positives
Monitor your reCAPTCHA analytics to find the optimal score for your use case.

​
hCaptcha

hCaptcha is a privacy-focused alternative to reCAPTCHA.

​
Configuration

​
NUXT_HCAPTCHA_SECRET_KEY
string
required
hCaptcha secret key from hCaptcha dashboard.
NUXT_HCAPTCHA_SECRET_KEY="0x4CCC..."
​
NUXT_HCAPTCHA_SITE_KEY
string
required
hCaptcha site key (public) from hCaptcha dashboard.
NUXT_HCAPTCHA_SITE_KEY="10000000-ffff-ffff-ffff-000000000001"

​
Setup Instructions

1

Create hCaptcha site

  1. Log in to hCaptcha Dashboard
  2. Click New Site
  3. Enter your domain (e.g., panel.example.com)
  4. Choose difficulty: Auto (recommended)
  5. Save
2

Get your keys

After creating the site:
  • Site Key - Displayed on the site list
  • Secret Key - Available in Settings
3

Configure environment

Add to your .env file:
CAPTCHA_PROVIDER="hcaptcha"
NUXT_HCAPTCHA_SECRET_KEY="your-secret-key"
NUXT_HCAPTCHA_SITE_KEY="your-site-key"
4

Restart application

Restart XyraPanel to apply the new configuration.

​
Protected Endpoints

Captcha verification is automatically applied to these endpoints:
EndpointPurpose
POST /api/auth/sign-in/*User login
POST /api/auth/sign-up/*User registration
POST /api/auth/forget-passwordPassword reset request
Captcha integration is handled automatically by better-auth. No additional code changes are needed.

​
Testing Captcha

​
Development Mode

For local testing, use provider-specific test keys: Turnstile: 
NUXT_PUBLIC_TURNSTILE_SITE_KEY="1x00000000000000000000AA"
NUXT_TURNSTILE_SECRET_KEY="1x0000000000000000000000000000000AA"
reCAPTCHA: Use localhost domain in reCAPTCHA admin panel. hCaptcha: Use localhost domain in hCaptcha settings.

​
Production Testing

1

Test login flow

Attempt to log in with correct credentials. Captcha should be validated automatically.
2

Test password reset

Request a password reset to verify captcha on that endpoint.
3

Monitor captcha analytics

Check your captcha provider’s dashboard for verification statistics.

​
Troubleshooting

Possible causes:
  • NUXT_PUBLIC_TURNSTILE_SITE_KEY not set (Turnstile)
  • JavaScript errors in browser console
  • Content Security Policy blocking captcha scripts
Solutions:
  • Check environment variables are set correctly
  • Check browser console for errors
  • Verify CSP allows captcha domains (see Security Configuration)
Possible causes:
  • Incorrect secret key
  • Domain mismatch (configured domain doesn’t match actual domain)
  • Using test keys in production
Solutions:
  • Verify NUXT_TURNSTILE_SECRET_KEY or equivalent is correct
  • Check domain configuration in captcha provider dashboard
  • Ensure you’re using production keys, not test keys
Possible causes:
  • NUXT_RECAPTCHA_MIN_SCORE set too high
  • Legitimate users flagged as suspicious
Solutions:
  • Lower NUXT_RECAPTCHA_MIN_SCORE to 0.3 or 0.4
  • Monitor reCAPTCHA analytics to find optimal score
  • Consider switching to Turnstile for better UX
Symptoms: Captcha blocked by Content Security PolicySolution: XyraPanel’s default CSP includes necessary captcha domains:
  • Turnstile: https://challenges.cloudflare.com
  • reCAPTCHA: Allowed via https: in script-src
  • hCaptcha: Allowed via https: in script-src
If you’ve customized CSP, ensure these domains are allowed.

​
Provider Comparison

FeatureTurnstilereCAPTCHA v3hCaptcha
PrivacyExcellentPoorGood
Free tierUnlimited1M assessments/monthUnlimited
User frictionVery lowNone (invisible)Low-Medium
AccuracyExcellentExcellentVery good
Setup difficultyEasyEasyEasy
Google dependencyNoYesNo
GDPR complianceYesRequires consentYes
AccessibilityExcellentGoodGood

​
Recommendations

Best for most users

Cloudflare TurnstileExcellent privacy, UX, and performance. No Google dependencies. Free and unlimited.

Best for Google ecosystem

Google reCAPTCHA v3Good if you’re already using Google services. Invisible to users but raises privacy concerns.

Best for privacy-first organizations

hCaptchaGood privacy and GDPR compliance. Slightly more visible to users than Turnstile.

​
Security Best Practices

Rotate your captcha keys every 6-12 months as part of security maintenance.
Regularly check your captcha provider’s dashboard for unusual patterns or verification failures.
Captcha works best alongside rate limiting. See Security Configuration.
Captcha is one layer of defense. Always implement other security measures like rate limiting, account lockouts, and monitoring.
Never commit secret keys to version control. Use environment variables and secure secret management.

​
Switching Providers

To switch captcha providers:
1

Update environment variables

Remove old provider’s keys and add new provider’s keys in .env.
2

Change CAPTCHA_PROVIDER

Update CAPTCHA_PROVIDER to your new provider:
CAPTCHA_PROVIDER="turnstile"
3

Restart application

Restart XyraPanel to load the new configuration.
4

Test authentication

Verify login and password reset work with the new provider.
Users with active sessions won’t be affected by the switch, but new authentication attempts will use the new provider immediately.

​
Next Steps

Security Configuration

Configure rate limiting and CORS

Environment Variables

View all configuration options

Build docs developers (and LLMs) love

Get started for freeTalk to us