Turnstile Verify

Verify Cloudflare Turnstile tokens server-side by calling the siteverify API from a Worker. This experiment uses the TURNSTILE_SECRET_KEY environment secret - there is no Turnstile Worker binding.

API Reference

POST /verify

Validates a client Turnstile token against the Cloudflare siteverify endpoint and returns the verification result.

Example Request

curl -X POST "https://your-worker.workers.dev/verify" \
  -H "Content-Type: application/json" \
  -d '{"token":"0.abc123..."}'

Success Response

success boolean

Whether Turnstile accepted the token

hostname string (optional)

Hostname associated with the token, when provided by siteverify

action string (optional)

Custom action name from the widget, when provided by siteverify

errorCodes string[] (optional)

Present when success is false; Turnstile error codes from siteverify

{
  "success": true,
  "hostname": "example.com",
  "action": "login"
}

When verification fails:

{
  "success": false,
  "errorCodes": ["invalid-input-response"]
}

Error Response

{
  "error": "Missing or invalid field: token",
  "code": "INVALID_TOKEN"
}

Error Codes

• 400 - Invalid JSON body (INVALID_BODY)
• 400 - Missing or invalid token (INVALID_TOKEN)
• 502 - Turnstile secret key is not configured (MISSING_SECRET)
• 502 - Siteverify request failed (VERIFY_ERROR)

Use Cases

• Validate Turnstile tokens on form submission before processing requests
• Protect login, signup, or contact endpoints from bots at the edge
• Learn server-side Turnstile verification without a backend framework
• Return structured siteverify results to your frontend or API gateway

Limitations

• Requires a TURNSTILE_SECRET_KEY secret configured in the Worker
• Server-side verification only; does not render the Turnstile widget
• Turnstile tokens are single-use and expire quickly

Deployment

cd apps/experiments/turnstile-verify
npx wrangler secret put TURNSTILE_SECRET_KEY

curl -X POST "https://your-worker.workers.dev/verify" \
  -H "Content-Type: application/json" \
  -d '{"token":"YOUR_TURNSTILE_TOKEN"}'

Local Development

cd apps/experiments/turnstile-verify
npm install
npx wrangler secret put TURNSTILE_SECRET_KEY
npm run dev

Test locally:

curl -X POST "http://localhost:8787/verify" \
  -H "Content-Type: application/json" \
  -d '{"token":"YOUR_TURNSTILE_TOKEN"}'

Cloudflare Features Used

• Workers - Edge compute runtime
• Cloudflare Turnstile - siteverify API for token validation