Bot Protection

Overview

To safeguard your Auth API against automated attacks from scripts and bots, you can implement Cloudflare’s Turnstile. Turnstile offers CAPTCHA-like protection without user friction, as it doesn’t require solving puzzles.

Integration Benefits

1. Selective Protection: Auth integrates Turnstile specifically for:
   • Signup requests via email/password, passwordless email, email OTP, passwordless SMS, ID token, and WebAuthn
   • Password reset requests
   • Signin requests that trigger an email or SMS: magic-link email, email OTP, and SMS OTP
2. API Accessibility: Other API endpoints remain accessible for legitimate programmatic use. The following are explicitly excluded, so clients don’t need to deliver a Turnstile token on them:
   • Verification endpoints (for example /signin/otp/email/verify, /signup/webauthn/verify, /signin/passwordless/sms/otp)
   • OAuth2 callback endpoints (/signin/provider/{provider}/callback)
   • OAuth2 redirect initiators (/signin/provider/{provider} and /signup/provider/{provider}) — these are GET redirects that the browser navigates to via window.location, which cannot carry custom headers
3. Bot Deterrence: Manual verification during signup discourages unwanted bot activity.

This approach balances security with usability, ensuring robust protection where it matters most.

Guide

Create a widget on Cloudflare

Sign up on Cloudflare if you haven’t already.

Go to your account -> Turnstile -> Add Widget. Then:

• Set a descriptive name
• In the domain, enter your frontend’s domain
• Set widget mode as “managed”

Then click on “create” and write down the site key and the secret key.

Enable Turnstile integration on auth

Start by adding the following configuration to your Nhost project:

Config

[auth.signUp.turnstile]
secretKey = 'turnstileSecretKey'

Replace turnstileSecretKey with the secret key from the first step.

Integrate turnstile into your sign up form

To integrate turnstile into your sign up form you can refer to Cloudfare’s documentation. Just keep in mind a few things:

• You don’t need to do any verification of the response, just pass it to the Auth service on any protected /signup/..., passwordless /signin/..., or /user/password/reset request in the header x-cf-turnstile-response.
• The “server side verification” is done by the auth service and will return a forbidden status error if the header is not present or if the check didn’t pass.
• You will need to use the site key from step 1 to configure turnstile in your form

Pass turnstile’s response to the signup request

To pass the response as a header change your request to include the header. For instance:

await signUpEmailPassword(
   email,
   password,
   {
     displayName,
   },
   {
     headers: {
       'x-cf-turnstile-response': turnstileResponse,
     },
   },
 );