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
Check Email	POST	/api/v1/auth/email/exists
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": "Pole Bezpečnostný token je povinné. (a 1 ďalších chýb)",
  "errors": {
    "turnstileToken": [
      "Pole Bezpečnostný token je povinné."
    ]
  }
}

Invalid Token

422 Unprocessable Entity

{
  "message": "Bezpečnostné overenie zlyhalo, skúste to znova.",
  "errors": {
    "turnstileToken": [
      "Bezpečnostné overenie zlyhalo, skúste to znova."
    ]
  }
}

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