hCaptcha Configuration
hCaptcha is a privacy-focused CAPTCHA service designed to protect your application from automated bot attacks. It supports both visible and invisible challenge types and helps safeguard critical authentication workflows such as registration, login, and password recovery.
This guide walks you through how to configure hCaptcha within the LoginRadius Admin Console, enable it for selected authentication APIs, and integrate it into your frontend using either the LoginRadius API or JavaScript SDK.
Refer to hCaptcha's official documentation for widget setup, UI customization, and token handling.
Configuration
- Get hCaptcha Keys
- Configure in LoginRadius
- Enable for Authentication
To get started:
- Log in to your hCaptcha dashboard.
- For an existing site, click the Settings (gear icon) next to the site name.
- To register a new site, click New Site and provide:
- Site Name
- Domains: Add domains where hCaptcha will be active
- Behavior & Threshold: Choose challenge type and difficulty
- After submission, you’ll get:
- Site Key
- Secret Key: Found under Profile Icon > Settings
Once you have your Site Key and Secret Key:
- Log in to the LoginRadius Admin Console
- Go to Security > Attack Protection > Bot Protection > CAPTCHA Providers
- Select hCaptcha from the CAPTCHA provider list
- Enter the Site Key and Secret Key
- Click Save
To enable hCaptcha protection for specific authentication workflows in your application:
- Log in to the LoginRadius Admin Console.
- Navigate to Security > Attack Protection > Bot Protection > CAPTCHA Providers.
- Ensure that Bot Protection is toggled on.
- Scroll to the Bot Protection Allowed On APIs section.
- Enable hCaptcha protection for the flows you want to secure:
- Login – Prevent brute-force or credential-stuffing attacks
- User Registration – Block fake or automated sign-ups
- Forgot Password – Protect password recovery endpoints from abuse
- Select if it is needed for any other APIs also.
- Click Save to apply the changes.
✅ Tip: You can selectively enable hCaptcha on one or multiple APIs depending on your risk tolerance and security goals.
CAPTCHA Implementation by Use Case
Before integrating, ensure your UI includes the hCaptcha widget. You can render this on your forms (registration, login, forgot password, etc.). Once the user completes the CAPTCHA challenge, hCaptcha will return a response token. To validate the interaction, this token must be passed in your LoginRadius API requests.
For guidance on rendering the widget and handling the token, refer to hCaptcha's official documentation.
Captcha Implementation on Registration Form
Integrate hCaptcha in your registration flow to prevent automated signups.
- Using LoginRadius API
- Using JS Library
Pass the hCaptcha response token in the Registration API call:
{
"email": "[email protected]",
"password": "UserPassword123",
"h_captcha_response": "VALIDATION_TOKEN"
}
Endpoint:
POST https://api.loginradius.com/identity/v2/auth/register
Use the following hook to inject hCaptcha into the registration form:
LRObject.$hooks.register('beforeFormRender', function(name, schema) {
if (name === 'registration') {
LRObject.util.addRecaptchaJS();
LRObject.util.captchaSchema("loginradius-hcaptcha_widget_registration", schema);
}
});
Captcha Implementation on Login Form
Protect login attempts with hCaptcha to reduce brute-force attacks.
- Using LoginRadius API
- Using JS Library
Pass the hCaptcha response token in your Login API request:
{
"email": "[email protected]",
"password": "UserPassword123",
"h_captcha_response": "VALIDATION_TOKEN"
}
Endpoint:
POST https://api.loginradius.com/identity/v2/auth/login
Use the following hook to inject hCaptcha into the login form:
LRObject.$hooks.register('beforeFormRender', function(name, schema) {
if (name === 'login') {
LRObject.util.addRecaptchaJS();
LRObject.util.captchaSchema("loginradius-hcaptcha_widget_login", schema);
}
});
Captcha Implementation on Forgot Password Form
Ensure the password recovery process is protected against bot misuse.
- Using LoginRadius API
- Using JS Library
Pass the hCaptcha response token in your Forgot Password API request:
{
"email": "[email protected]",
"h_captcha_response": "VALIDATION_TOKEN"
}
Endpoint:
POST https://api.loginradius.com/identity/v2/auth/password
Use the following hook to inject hCaptcha into the Forgot Password form:
LRObject.$hooks.register('beforeFormRender', function(name, schema) {
if (name === 'forgotpassword') {
LRObject.util.addRecaptchaJS();
LRObject.util.captchaSchema("loginradius-hcaptcha_widget_forgotpassword", schema);
}
});
Language Customization
To change the hCaptcha language dynamically, pass the hl parameter in the script URL:
<script src="https://js.hcaptcha.com/1/api.js?hl=fr" async defer></script>
Replace fr with your preferred language code.
For a full list of supported languages, refer to the hCaptcha language documentation.
Admin Console hCaptcha Options
LoginRadius supports two hCaptcha behaviors:
- Checkbox + Challenge: A visible checkbox, challenge appears as needed.
- Challenge Only: Invisible CAPTCHA that appears automatically when triggered.