How to Test Cloudflare Turnstile in Authorized QA

There are two different ways to test a Turnstile integration. For predictable development and automated tests of your own application, start with Cloudflare's official test sitekey and test secret. If you also need to exercise a real challenge flow on a site you are authorized to test, SolveHub can create a Turnstile task and return a response token.

These methods are not interchangeable. SolveHub does not issue Cloudflare's dummy test tokens, and a production secret will not validate a dummy token from an official test sitekey.

Choose the Right Test Method

• Goal: test form success, failure or retry behavior in your own development or CI environment. Use: Cloudflare's official test sitekey and matching test secret. Why: predictable results without creating a paid SolveHub task.
• Goal: test a real Turnstile challenge in a permitted QA workflow. Use: your authorized page's real URL and sitekey with a SolveHub Turnstile task. Why: it exercises the live integration rather than a dummy-key fixture. Check availability and pricing first.

Option 1: Use Cloudflare's Official Test Keys

Configure a test sitekey in your test environment and the matching test secret on your server. Cloudflare provides keys for successful validation, failed validation and other test scenarios. Keep test credentials out of production configuration, and continue to verify tokens server-side.

For the current keys and expected behavior, follow Cloudflare's official Turnstile testing documentation. You do not need a SolveHub task for this option.

Option 2: Test a Live Challenge with SolveHub

Use this route only for a website and workflow you have permission to test. You need an active SolveHub key with the tasks permission, sufficient balance, and a currently available Turnstile task type. Register and verify your email, then activate self-service if available or bind a key issued by SolveHub.

Create a task with the full page URL as websiteURL and that page's Turnstile sitekey as websiteKey. Include action or cdata only if the widget actually uses them. Send an Idempotency-Key and save the returned taskId.

{"type":"turnstile","task":{"websiteURL":"https://example.com/login","websiteKey":"REPLACE_WITH_SITE_KEY"}}

curl -sS -X POST 'https://www.tiam.codes/v1/tasks' \
  -H "Authorization: Bearer $SOLVEHUB_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: authorized-test-0001' \
  --data-binary @task.json

Poll GET /v1/tasks/{taskId} about every 2–3 seconds. Read solution.value only after status is completed, and do not treat HTTP 200 alone as completion. Pass the response token through your own application's supported flow, including server-side verification. Never expose your SolveHub API key in browser JavaScript. The Turnstile field reference documents optional cdata, action and proxy fields.

Handle Timeouts and Errors Safely

A local timeout does not mean the task was cancelled. If its status becomes uncertain, continue checking the same taskId instead of creating a replacement with a new idempotency key; the reserved amount is not released by a client deadline. See retrying without duplicates and safe polling.

For HTTP 402, check balance. For 429, reduce request rate and respect retry guidance. For 503, check availability and retry the original request only within a bounded budget. A wrong page URL, sitekey, action or cdata can also make a test invalid.

Next Steps

Read the Turnstile field reference for exact request parameters, the quick start for task creation and polling, and Cloudflare's testing documentation before choosing between dummy-key tests and live QA. Live availability and per-task prices are on the pricing page.