Captcha

This documentation outlines the CAPTCHA protection implemented in the Harmoney application to guard the white label registration flow against automated abuse. Harmoney uses Cloudflare Turnstile as its CAPTCHA provider.

How it works

When CAPTCHA protection is enabled for a white label, a Cloudflare Turnstile widget is rendered on the registration page and the user must pass the challenge before their registration is accepted:

1. The registration page renders the Turnstile widget using the white label's public site key.
2. When the challenge is completed, Turnstile returns a response token to the browser.
3. On submitting the registration, the token is sent to the Harmoney back-end.
4. The back-end verifies the token server-side by calling the Turnstile siteverify endpoint with the white label's secret key. Registration only proceeds when verification succeeds.

If CAPTCHA is enabled but the token is missing or cannot be validated, the registration request is rejected.

When CAPTCHA protection is disabled, no widget is shown and registration proceeds without a challenge.

Configuration overview

CAPTCHA protection is configured per white label. The settings live on the white label's settings.captcha object and can be edited through the Details card on the white label detail page (or via configuration import/export).

White label

Setting	Technical name	Description
Captcha enabled	enabled	Whether CAPTCHA protection is enabled for this white label's registration flow.
Captcha site key	siteKey	Public Cloudflare Turnstile site key used to render the CAPTCHA widget. Required when CAPTCHA is enabled.
Captcha secret key	secretKey	Cloudflare Turnstile secret key used to verify CAPTCHA tokens. Required when CAPTCHA is enabled.
Captcha verification URL	url	Base URL of the Cloudflare Turnstile verification endpoint. Defaults to https://challenges.cloudflare.com when left empty.

The site key and secret key are obtained from the Cloudflare Turnstile dashboard when creating a Turnstile widget for the white label's domain.

When Captcha enabled is turned on, the site key and secret key become required in the form. The verification URL is optional and only needs to be set to override the default Cloudflare Turnstile endpoint.

Example settings.captcha configuration:

{
  "enabled": true,
  "siteKey": "0x4AAAAAAA_example_site_key",
  "secretKey": "0x4AAAAAAA_example_secret_key",
  "url": "https://challenges.cloudflare.com"
}

note

CAPTCHA protection currently applies to the registration flow only.