Get Turnstile Credentials

To use Cloudflare Turnstile for bot protection in your Mindful Auth portal, you need to obtain Turnstile credentials (site key and secret key) for each hostname you onboard. Each tenant must provide their own Cloudflare Turnstile credentials during onboarding.

1. Create a Cloudflare Account

If you don’t have one, create a free Cloudflare account at cloudflare.com.

2. Create a Turnstile Widget

1. Go to Cloudflare Dashboard → Turnstile
2. Click Add Widget
3. Configure the widget:
   • Name: Your portal name (e.g., “My Company Portal”)
   • Domains: Add your portal domain (e.g., portal.yourcompany.com) — This is required before onboarding
   • Mode: Managed (recommended)
   • Pre-clearance: Disabled (recommended)
4. Click Create
5. Copy the Site Key and Secret Key

⚠️ Important: You must add your hostname to the widget’s domain list in Cloudflare before onboarding. The worker does not automatically add hostnames to your Turnstile widget.

3. Provide Credentials During Onboarding

When onboarding your hostname, provide both keys:

• turnstileSitekey: The public site key (starts with 0x4A...)
• turnstileSecretKey: The secret key (starts with 0x4AAA...)

Example onboarding request:

{
  "hostname": "portal.yourcompany.com",
  "backendType": "tape",
  "turnstileSitekey": "0x4AAAAAAAxyz123...",
  "turnstileSecretKey": "0x4AAAAAAAsecret456...",
  ...
}

How It Works

Frontend Flow

1. Portal page loads turnstile-init.js script
2. Script calls GET /auth/get-tenant-config to fetch the tenant’s sitekey
3. Script renders Turnstile widget with tenant-specific sitekey
4. User completes challenge, token is added to form

Backend Flow

1. Form submission includes cf-turnstile-response token
2. Worker decrypts tenant’s secret key from Cloudflare KV storage
3. Worker verifies token with Cloudflare using tenant’s secret key
4. Request proceeds if verification passes

Frontend Integration

Add these scripts to your portal pages that need bot protection:

<!-- Turnstile library -->
<script src="https://challenges.cloudflare.com/turnstile/v0/api.js" async defer></script>

<!-- Auto-init script (fetches tenant sitekey automatically) -->
<script src="https://cdn.mindfulauth.com/scripts/turnstile-init.js"></script>

<!-- Widget container -->
<div id="turnstile-container"></div>

Widget Customization

Customize the widget using data attributes on the container div:

<!-- Dark theme -->
<div id="turnstile-container" data-theme="dark"></div>

<!-- Compact size -->
<div id="turnstile-container" data-size="compact"></div>

<!-- Spanish language -->
<div id="turnstile-container" data-language="es"></div>

<!-- Invisible mode -->
<div id="turnstile-container" data-appearance="execute"></div>

<!-- Multiple customizations -->
<div id="turnstile-container"
     data-theme="dark"
     data-size="compact"
     data-language="fr"></div>

Available Options:

• data-theme: light (default), dark, auto
• data-size: flexible (default), normal, compact
• data-language: auto (default), or language code
• data-appearance: always (default), execute, interaction-only

Updating Turnstile Credentials

To rotate or update Turnstile credentials go to the edit hostname page here. More information here Edit Hostname Guide. Note: Both keys must be provided together when updating.

Troubleshooting

”Bot protection validation failed”

• Cause: Invalid or expired Turnstile token
• Solution: Ensure widget is properly rendered, check for JavaScript errors

”Turnstile widget not appearing”

• Causes:
  • Domain not added to widget in Cloudflare dashboard (must be done before onboarding)
  • Tenant config not found
• Solutions:
  • Add your portal domain to Turnstile widget settings in Cloudflare, then re-test
  • Verify tenant is onboarded with correct hostname

”Missing turnstileSitekey in config”

• Cause: Tenant onboarded without Turnstile credentials
• Solution: Update hostname with Turnstile credentials via admin endpoint

Token Always Rejected

• Causes:
  • Wrong secret key provided during onboarding
  • Sitekey/secret key mismatch
• Solutions:
  • Verify you copied both keys from the same widget
  • Re-onboard or update with correct credentials

Security Notes

1. Secret key is encrypted at rest: Stored with AES-GCM encryption in Cloudflare KV
2. Never expose secret key in frontend: Only the sitekey is public
3. Rotate keys if compromised: Use update endpoint to change credentials
4. Multiple hostnames per widget: You can add multiple of your hostnames to a single Turnstile widget if you prefer to manage them together