How Do I Configure and Troubleshoot Bot Protection for Identity Management?

Supported Bot Protection Options

Google reCAPTCHA

• reCAPTCHA v3 (recommended): Runs invisibly in the background, scoring user interactions without interruption. Requires a valid v3 site key and v3 secret key for the domain(s) where Identity Management is hosted.

• reCAPTCHA v2: Presents a visible challenge to users. Useful as a temporary fallback if v3 is failing or while you resolve configuration issues.

Cloudflare Turnstile

Cloudflare Turnstile is a privacy-friendly, user-invisible CAPTCHA alternative that does not rely on tracking cookies or behavioral profiling. It validates users silently using Cloudflare's smart signals, without requiring any visible challenge in most cases.

Key characteristics:

• No visible puzzle or checkbox for the majority of users

• Privacy-preserving — no user data sold or used for ad targeting

• Integrates with Cloudflare's broader bot management network

Where to Configure Bot Protection in Piano

In the Piano dashboard, navigate to:

Edit business → User provider → (Edit) → Security policy

In Security policy, you can:

• Select reCAPTCHA v3, reCAPTCHA v2, or Cloudflare Turnstile

• Enter the corresponding site key and secret key for the selected provider

Configuring Google reCAPTCHA

Important Behavior (v3)

If reCAPTCHA v3 is selected but no credentials are entered, Piano may fall back to default keys intended for Piano-hosted domains (e.g., sandbox.tinypass.com, id.piano.io). This commonly breaks on custom domains and results in domain-related reCAPTCHA errors.

Whitelabeled/Custom Domains: You Must Register Each Domain with Google

If you use domain whitelabeling (custom domains for Identity Management), Google reCAPTCHA must recognize those domains. Keys that work for Piano's default domains cannot be reused for your whitelabeled domain(s).

Requirements:

• Register each whitelabeled domain in the Google reCAPTCHA admin console.

• Generate a unique site key and secret key for the domain(s).

• Enter those keys in Piano under Security policy.

Enable reCAPTCHA on Registration vs. Login

In Security policy, set Require reCAPTCHA based on your desired coverage:

• Registration (default use case)

• Registration and Login (adds reCAPTCHA to the Piano ID Login Page template as well)

No template changes are required unless you have custom templates (see Form Behavior with Custom Templates).

Configuring Cloudflare Turnstile

Prerequisites

• A Cloudflare account with Turnstile enabled

• The domain(s) where Identity Management is hosted must be registered in the Cloudflare Turnstile dashboard

Setup Steps

1. Log in to the Cloudflare dashboard and navigate to Turnstile.

2. Create a new Turnstile widget and add all relevant domains (including any whitelabeled Identity Management domains).

3. Copy the Site Key and Secret Key from the Cloudflare Turnstile dashboard.

4. In Piano, navigate to Edit business → User provider → (Edit) → Security policy.

5. Select Cloudflare Turnstile as the bot protection method.

6. Enter the Turnstile Site Key and Secret Key.

7. Save and test on each affected domain.

Whitelabeled/Custom Domains with Turnstile

As with reCAPTCHA, each whitelabeled domain must be explicitly added to your Turnstile widget configuration in Cloudflare. Turnstile will reject token validation for any domain not listed in its allowed domains.

Known Limitations

• Some edge cases in custom template flows may not be fully supported.

• Fallback behavior (e.g., automatic switch to v2 reCAPTCHA on failure) is not currently supported for Turnstile.

Common Errors and How to Fix Them

reCAPTCHA: "Invalid domain for site key"

This error is generated by the Google reCAPTCHA client-side script, not by a Piano-specific log. Troubleshoot by checking the browser console on the affected page.

Most common causes and fixes:

1. Wrong or unregistered domain in Google — In the Google reCAPTCHA admin console, ensure the domain where Identity Management is running is included/authorized. Make sure you are testing on the exact domain you registered (including the correct host/subdomain).

2. Using Piano default keys on a custom domain — If you are on a whitelabeled domain, generate keys for that domain and paste them into Piano (Security policy → v3 site key / v3 secret key).

3. Incorrect keys in Piano — Re-enter the keys carefully (no extra characters or spaces). Confirm the site key and secret key are from the same reCAPTCHA configuration in Google.

4. Propagation/caching — Changes in Google settings can take time to apply. If you recently updated keys, verify the rendered page source or network responses to confirm no older key is being served from cache.

reCAPTCHA: "site-key/secret mismatch — verification failed"

This typically indicates the site key and secret key do not match each other or don't align with the configured domain(s).

Fix checklist:

• Confirm the v3 site key and v3 secret key in Piano match the same key pair in Google.

• Confirm the Google reCAPTCHA configuration authorizes the domains you are testing.

• If the issue affects only one domain or environment, compare that environment's keys and domain settings to working environments.

Cloudflare Turnstile: Token Validation Failure

If Turnstile token verification fails server-side, check the following:

• Confirm the Site Key and Secret Key in Piano match the same widget in the Cloudflare dashboard.

• Verify the domain is listed under the Turnstile widget's allowed domains in Cloudflare.

• Check that you are not mixing keys from different Turnstile widgets or environments.

• Review Cloudflare's Turnstile analytics dashboard for rejection signals or error codes.

Form Behavior with Custom Templates

If you use custom Identity Management templates for registration or login, ensure your template still includes the bot protection component expected by Identity Management.

For registration templates using reCAPTCHA, verify the component is present:

<re-captcha *hideIfAuthCompleted></re-captcha>

Immediate Workaround if Bot Protection Is Blocking Users

If users cannot register or log in due to bot protection failures and you need a quick restore:

• If using reCAPTCHA v3: Switch to reCAPTCHA v2 in Security policy, then return to v3 after correcting domain registration and key configuration.

• If using Cloudflare Turnstile: Switch to reCAPTCHA v2 or v3 while you work with your Piano account team to resolve the Turnstile configuration.

Key Takeaways

• Custom/whitelabeled domains require their own registration and keys for both Google reCAPTCHA and Cloudflare Turnstile.

• For reCAPTCHA v3, you must configure a valid site key and secret key in Piano for all domains in use.

• "Invalid domain for site key" is almost always a domain/key authorization problem in Google, or a mismatch between the domain being used and the keys configured in Piano.

• If you are blocked by bot protection failures, temporarily switch to reCAPTCHA v2 while you resolve the underlying configuration.

Last updated: June 26, 2026