Turnstile Integration

Cloudflare Turnstile protects authentication endpoints from bots. This guide covers what the API expects from frontend implementations.

For frontend widget setup, see the Cloudflare Turnstile documentation.

Protected Endpoints

The following endpoints require a turnstileToken when bot protection is enabled:

Endpoint	Method	Path
Login	POST	/api/v1/auth/login
Register Client	POST	/api/v1/auth/register/client
Register Expert	POST	/api/v1/auth/register/expert
Send Password Reset Email	POST	/api/v1/auth/password/email
Resend Verification Email	POST	/api/v1/auth/email/verify/resend

Request Format

Include the turnstileToken field in the request body:

{
  "email": "user@example.com",
  "password": "SecurePass123",
  "turnstileToken": "0.XXXXXXXXXXXXXXXXXXXX..."
}

Error Responses

Missing Token

422 Unprocessable Entity

{
  "message": "The turnstile token is required. (and 1 more error)",
  "errors": {
    "turnstileToken": [
      "The turnstile token is required."
    ]
  }
}

Invalid Token

422 Unprocessable Entity

{
  "message": "The turnstile token verification failed.",
  "errors": {
    "turnstileToken": [
      "The turnstile token verification failed."
    ]
  }
}

Testing

Cloudflare Test Keys

Key Type	Site Key	Secret Key
Always passes	1x00000000000000000000AA	1x0000000000000000000000000000000AA
Always fails	2x00000000000000000000AB	2x0000000000000000000000000000000AB
Forces challenge	3x00000000000000000000FF	N/A

Disabling in Development

Set in your environment:

TURNSTILE_ENABLED=false

When disabled, all tokens are accepted without Cloudflare verification.

Production

Always enable Turnstile in production (TURNSTILE_ENABLED=true).

Security Notes

Best Practices

• Never expose your Secret Key in frontend code
• Tokens are single-use and expire after verification
• Always verify tokens server-side
• Consider rate limiting alongside Turnstile