Skip to main content
CAPTCHA helps protect your application from automated bot attacks, spam, and abuse by verifying that interactions are coming from real users.

​
CAPTCHA integration

Stytch’s SDK integrates with popular CAPTCHA providers to add bot protection to your authentication flows. CAPTCHA challenges can be added to various authentication methods to prevent automated attacks.

​
Supported CAPTCHA providers

​
reCAPTCHA

Google’s reCAPTCHA is the most widely-used CAPTCHA solution. Stytch supports both reCAPTCHA v2 and v3:
  • reCAPTCHA v2: Presents users with an explicit challenge (checkbox or image selection)
  • reCAPTCHA v3: Runs invisibly in the background, scoring user interactions without interrupting the flow

​
hCaptcha

An alternative CAPTCHA provider focused on privacy and accessibility. hCaptcha is compatible with Stytch’s SDK and can be used as a drop-in replacement for reCAPTCHA.

​
Configuration

Configure CAPTCHA settings in your Stytch Dashboard under Project Settings → Security. You’ll need to:
  1. Enable CAPTCHA protection for your project
  2. Choose your CAPTCHA provider (reCAPTCHA or hCaptcha)
  3. Add your site key and secret key from your CAPTCHA provider
  4. Select which authentication methods require CAPTCHA verification

​
Implementation

When CAPTCHA is enabled for your project, you’ll need to include the CAPTCHA token in authentication requests: 
// Example: Email magic link with CAPTCHA
const response = await stytch.magicLinks.email.loginOrCreate({
  email: 'user@example.com',
  captcha_token: captchaToken // Include CAPTCHA token from provider
});

​
Client-side integration

Include the CAPTCHA provider’s JavaScript library in your application: For reCAPTCHA: 
<script src="https://www.google.com/recaptcha/api.js" async defer></script>
For hCaptcha: 
<script src="https://js.hcaptcha.com/1/api.js" async defer></script>

​
Obtaining CAPTCHA tokens

Before calling Stytch authentication methods, execute the CAPTCHA challenge and obtain a token: reCAPTCHA v2: 
grecaptcha.execute();
// Token is returned via callback or promise
reCAPTCHA v3: 
grecaptcha.ready(() => {
  grecaptcha.execute('YOUR_SITE_KEY', {action: 'login'})
    .then((token) => {
      // Use token in Stytch authentication call
    });
});
hCaptcha: 
hcaptcha.execute();
// Token is returned via callback

​
Authentication methods with CAPTCHA

CAPTCHA can be added to protect these authentication methods:

​
Best practices

​
When to use CAPTCHA

  • Sign-up flows: Prevent automated account creation
  • Login pages: Protect against credential stuffing attacks
  • Password reset: Block password reset spam
  • High-volume endpoints: Any endpoint experiencing bot traffic

​
User experience

  • Use reCAPTCHA v3 when possible: Provides protection without user interaction
  • Fallback to v2 for low scores: Only show challenges to suspicious traffic
  • Clear error messages: Inform users if CAPTCHA verification fails
  • Accessibility: Ensure CAPTCHA doesn’t block legitimate users with disabilities

​
Security

  • Server-side verification: Always verify CAPTCHA tokens server-side (Stytch handles this)
  • Rate limiting: Combine CAPTCHA with rate limiting for comprehensive protection
  • Monitor bypass attempts: Watch for patterns of CAPTCHA failures
  • Rotate keys regularly: Update your CAPTCHA keys periodically

​
Troubleshooting

​
CAPTCHA verification failures

If CAPTCHA verification is failing:
  • Verify your site key and secret key are correct in the Stytch Dashboard
  • Check that you’re using the correct domain (CAPTCHA keys are domain-specific)
  • Ensure the CAPTCHA token is fresh (tokens expire after a few minutes)
  • Verify your application’s domain is whitelisted with your CAPTCHA provider

​
Testing

During development, you can use test keys provided by CAPTCHA providers that always pass/fail for testing purposes. Remember to switch to production keys before going live.

​
Performance considerations

CAPTCHA can impact page load time and user experience:
  • Load CAPTCHA scripts asynchronously
  • Consider lazy-loading CAPTCHA only when needed
  • Use reCAPTCHA v3 to minimize user interaction
  • Cache CAPTCHA tokens when appropriate for multiple operations