Config
Using Turnstile is the same ground with the code around it, bot-gating a route is the walkthrough, and provisioning mints the keys these names point at. Refusals carry an ordinary error code.
| Key | What it is |
|---|---|
widgets.visible | The managed widget — a challenge where it should be seen |
widgets.invisible | The silent widget — a form that should not be interrupted |
widgets.<mode>.sitekeys | Each environment’s public sitekey — dev, staging, prod, and an optional feature. pithy turnstile provision writes them, and the build inlines them |
protect | Action → widget mode. Which protected actions get a gate, at which mode |
token | Where the token goes: field (default cf-turnstile-response) or header. It reaches the browser through the client projection, so a screen sends the token there, and auth’s sign-in gate reads it from there too. A turnstile() you stack on your own route does not read this key: it takes its own field and header options |
Up to two widgets per domain, one of each mode. Declare only the modes you need.
The widget secret is never in config. Only the public sitekeys are — the front end renders with them. The secret is stored and read through the secrets capability.
protect defaults to { login: "visible" }, and that default is built from the login-action constant rather than written out again — the key an action is configured under and the action label a token is solved for are the same string.
Middleware options
turnstile({ mode, field, header, action })| Option | Default | |
|---|---|---|
mode | Inferred | Which widget. Required only when both are declared |
field | cf-turnstile-response | The body field, form or JSON |
header | — | Read from a request header instead. For a JSON API or a mobile client sending the token out of band |
action | — | The expected action label. Denies on mismatch |
Error codes
| Code | Status | Cause |
|---|---|---|
turnstile/missing_token | 400 | No token where one was expected |
turnstile/failed | 403 | The token did not pass, or the response was unusable |
turnstile/config | 500 | The deployment is at fault: no widget secret is stored for this environment outside a feature build, the secret is malformed or has no entry for the route’s mode, Cloudflare does not recognize it, a test key answered outside dev, staging and feature, or a real widget is in force with no turnstile-account recorded |
turnstile/analytics_window | 400 | The widget read asked for a window past what Cloudflare keeps, or wider than one read may ask for. The message names the cap |
turnstile/analytics_unavailable | 409 | Cloudflare serves no Turnstile analytics to this account |
turnstile/analytics_forbidden | 409 | The Worker’s runtime token lacks Account Analytics Read. params.permission names it, and the message names the rotate that adds it |
turnstile/failed covers a transport error, a non-OK status, a non-JSON body and an unrecognized response shape — every one of them denies. turnstile/config is separated out because it is a verdict about the deployment rather than about the caller.
What is sent to siteverify
secret, response, and remoteip when available. That is all.
Siteverify takes no action request parameter — the action is a response field the caller compares. A gate that tried to send it would be sending a parameter Cloudflare ignores and believing it had checked something.
What is read back
| Field | Used for |
|---|---|
success | The verdict |
error-codes | Which failure, including the two that name the secret |
action | Compared against the expected action |
metadata.result_with_testing_key | Cloudflare’s own flag that this verdict came from a test key |
Cloudflare may add fields; the schema strips them. Validating the body is part of the security boundary, not tidiness.
The two secret-fault codes
invalid-input-secret and missing-input-secret are the codes that name the secret rather than the token. Every other code is a verdict about the caller; these two are a verdict about the deployment, and they are what raises turnstile/config.
Where provisioning writes
| What | Where |
|---|---|
| Each environment’s public sitekey | widgets.<mode>.sitekeys.<environment> in the Worker’s pithy.config.ts |
| The widget secret | The secrets store: the dev secrets file for dev, the managed store for staging and prod |
turnstile-account | The same stores. The Cloudflare account the widgets live in — an account id, not a token |
No Worker var is written. A TURNSTILE_SITEKEY_* var an older provisioner left behind is read by nothing, and pithy doctor names it.
The widget read
GET /turnstile/admin/widgets is turnstile’s route on the control plane, behind the turnstile:widgets:read scope. It answers for the Worker it reaches: which widget guards this environment, whether it is a real one or a test key, and how its challenges went. A client asking about three environments asks three Workers.
| Query | Default |
|---|---|
since | 30 days before until. ISO-8601, inclusive |
until | Now. ISO-8601, exclusive |
Every widget the config declares comes back in exactly one of four states.
state | Means | Cloudflare is asked |
|---|---|---|
reported | A real sitekey. Challenges issued, solved and unsolved, the solve rate, what siteverify passed and refused, and every event type counted | Yes, filtered by that sitekey |
test-key | One of Cloudflare’s documented test keys, where one belongs: dev, staging, a feature build. Its outcome is fixed, so it is never reported as zero challenges | No |
misconfigured | A test key anywhere else, prod included. The gate refuses its verdict, so nothing gets through. The message names pithy turnstile provision | No |
unconfigured | No sitekey is in force here, so no widget renders | No |
It reads on the application’s one runtime token. Turnstile adds analytics:read to that token’s permissions and holds no token of its own. A token minted before turnstile was composed lacks it, and the read answers turnstile/analytics_forbidden until pithy token rotate runtime --env prod replaces it; a mint only rolls the value. Cloudflare tokens has the model.
The account comes from turnstile-account, and it is read only when a real widget is in force. A real widget with no account recorded is turnstile/config; run pithy turnstile provision again to record it. The analytics dataset is account-wide, which is why the read filters by sitekey: it answers for this widget and no other.
The widget page
GET /turnstile/widget is public, and it is for a native app. It renders Cloudflare’s widget on the Worker’s own origin, for the sitekey this environment resolves and the login action auth’s gate asserts, and posts what happens as a JSON string to window.ReactNativeWebView:
| Message | When |
|---|---|
{ "type": "turnstile", "token": "…" } | Solved. Send token where config’s token says: the cf-turnstile-response body field by default, or the header it names |
{ "type": "turnstile-expired" } | The token lapsed, or the challenge timed out |
{ "type": "turnstile-error" } | The widget, or Cloudflare’s script, failed |
| Query | Default |
|---|---|
theme | auto. One of auto, light, dark |
language | auto, or a language tag such as es or pt-br |
It carries only what the client projection already ships: the public sitekey and the action. The page refuses to be framed and is never cached. Where no login widget is set up it answers 404. The production widget’s allowed hostnames must include the Worker’s origin, because that is where the page is served; pithy turnstile provision binds the widget there.