Skip to main content

hCaptcha

Community-contributed integration

This integration is community-maintained. Reference: ory/integrates/fraud-bot-protection/hcaptcha.

hCaptcha is a privacy-focused CAPTCHA service and an alternative to reCAPTCHA. It is GDPR-compliant and does not sell data. The Enterprise tier adds adaptive challenge difficulty.

How it works​

  1. Registration / login UI embeds the hCaptcha client widget; the widget runs the challenge and returns a token (h-captcha-response).
  2. Form submits to Ory's flow with the token.
  3. Ory Action on registration.after / login.after with can_interrupt: true calls the handler.
  4. Handler POSTs to https://api.hcaptcha.com/siteverify with the token
    • hCaptcha Secret; checks success == true.
  5. On fail, handler returns an error and Ory blocks.

Notable​

  • Two keys: Site Key (client widget) and Secret (server verify). Never expose Secret.
  • The token reaches the webhook in transient_payload, which exists only once the user submits the flow. Keep the action on the after trigger with can_interrupt: true: a before action runs when Ory Kratos Identities creates the flow and never sees the token.
  • Tokens are one-time use and expire 2 minutes after issue.
  • The hCaptcha API contract is nearly identical to reCAPTCHA, so you can migrate between the two with minimal changes.

Resources​