Turnstile reference

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.

KeyWhat it is
widgets.visibleThe managed widget — a challenge where it should be seen
widgets.invisibleThe silent widget — a form that should not be interrupted
widgets.<mode>.sitekeysEach environment’s public sitekey — dev, staging, prod, and an optional feature. pithy turnstile provision writes them, and the build inlines them
protectAction → widget mode. Which protected actions get a gate, at which mode
tokenWhere 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 })
OptionDefault
modeInferredWhich widget. Required only when both are declared
fieldcf-turnstile-responseThe 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

CodeStatusCause
turnstile/missing_token400No token where one was expected
turnstile/failed403The token did not pass, or the response was unusable
turnstile/config500The 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_window400The 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_unavailable409Cloudflare serves no Turnstile analytics to this account
turnstile/analytics_forbidden409The 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

FieldUsed for
successThe verdict
error-codesWhich failure, including the two that name the secret
actionCompared against the expected action
metadata.result_with_testing_keyCloudflare’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

WhatWhere
Each environment’s public sitekeywidgets.<mode>.sitekeys.<environment> in the Worker’s pithy.config.ts
The widget secretThe secrets store: the dev secrets file for dev, the managed store for staging and prod
turnstile-accountThe 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.

QueryDefault
since30 days before until. ISO-8601, inclusive
untilNow. ISO-8601, exclusive

Every widget the config declares comes back in exactly one of four states.

stateMeansCloudflare is asked
reportedA real sitekey. Challenges issued, solved and unsolved, the solve rate, what siteverify passed and refused, and every event type countedYes, filtered by that sitekey
test-keyOne 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 challengesNo
misconfiguredA test key anywhere else, prod included. The gate refuses its verdict, so nothing gets through. The message names pithy turnstile provisionNo
unconfiguredNo sitekey is in force here, so no widget rendersNo

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:

MessageWhen
{ "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
QueryDefault
themeauto. One of auto, light, dark
languageauto, 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.

ESC