Document undocumented siteverify fields

[ask-bonk]

Here is a summary of the investigation and changes:

API Validation Results

I tested the live Turnstile Siteverify API (POST https://challenges.cloudflare.com/turnstile/v0/siteverify) with all three test secret keys and various token combinations. Here is what I found:

Confirmed undocumented fields

Field	Confirmed	Details
metadata.result_with_testing_key	Yes	Present in ALL responses when using test secret keys (both success and failure). Always true. Not present with production or invalid keys.
messages	Yes (also undocumented)	Array present in all failure responses. Usually empty [], but contains a descriptive string for bad-request errors (e.g., wrong Content-Type).
tokenId	Not reproducible	Could not trigger this field with any test key or invalid credential combination. This may only appear with production keys under specific error conditions, or may be an internal/intermittent field. I did not add it to the docs since it cannot be verified.

Changes made

src/content/docs/turnstile/get-started/server-side-validation.mdx:

• Added messages and metadata.result_with_testing_key to the response fields table
• Updated the failed response example to include the messages field (matching real API output)

src/content/docs/turnstile/troubleshooting/testing.mdx:

• Updated all three test response examples (success, failure, token-already-redeemed) to match actual API responses, including metadata.result_with_testing_key and messages
• Fixed hostname from localhost to example.com in success response (matching actual API output)
• Added a note explaining that result_with_testing_key is only present with test keys and should not be relied upon for application logic

Regarding tokenId

I was unable to reproduce this field. It may be returned only under specific production conditions that cannot be triggered with test keys. I recommend the Turnstile team confirm whether this field is intentional API behavior before documenting it.

Closes #28249

github run

[github-actions]

This pull request requires reviews from CODEOWNERS as it changes files that match the following patterns:

Pattern	Owners
/src/content/docs/turnstile/	@migueldemoura, @punkeel, @patriciasantaana, @cloudflare/pcx-technical-writing

[elithrar]

/bonk good.

• add a table that shows the response format, type, optional and notes on each field to help users understand the purpose of each
• A copy-pastable TurnstileResponse interface that users can use in their client side apps
• Validate every code example and curl snippet for best practices and completeness
• Re-review your work. This page has a wide audience: make sure it is approachable, concise, and well-structured.

e.g. Process jumps straight into it with no preamble. Consider a Markdown fenced mermaid diagram that makes this flow easier to understand, including success vs failure paths .

[ask-bonk]

All changes are committed. Here is a summary of what was done:

Changes made to server-side-validation.mdx

Structure and approachability

• Replaced "Process" section with "How it works" -- added a prose preamble explaining the flow, followed by a mermaid sequence diagram showing Visitor -> Your Server -> Siteverify API with success/failure branching paths
• Tightened the caution admonition from 3 sentences to 1 sentence, removing redundancy
• Consolidated token characteristics -- removed the duplicate paragraphs that restated the bullet points, kept one concise paragraph about expiry recovery
• Renamed "Implementation" to "Full implementation example" with a descriptive preamble
• Renamed "Required parameters" to "Request parameters" (the table includes optional params too)

New reference content

• Response fields table now has 4 columns: Field, Type, Always present, Description -- making it clear which fields are guaranteed, success-only, failure-only, Enterprise-only, or test-only
• TypeScript TurnstileResponse interface -- copy-pastable, complete with all documented fields including messages and metadata
• curl quick-test example -- uses test keys so it works out of the box, with guidance on replacing with production credentials

Code example fixes

• PHP: Fixed $\_SERVER (escaped underscores) to $_SERVER, fixed indentation of if/else block
• PHP, Python, Java, C#: Fixed four-backtick ````` code fences to three backticks
• Retry example: Removed incorrect response.ok check (Siteverify always returns HTTP 200, even for failures) -- now correctly returns the result immediately and only retries on network catch errors
• Retry example: Removed const crypto = require("crypto") (CommonJS in async context); crypto.randomUUID() is available globally in modern runtimes

Minor fix to testing.mdx

• Removed stray blank line inside the shell code block for environment configuration

github run

[elithrar]

/bonk Great.

For any multi language code examples - e.g. JavaScript, Python, PHP: add a TypeScript tab and make it the primary.

validate the code is correctly typed, adheres to best practices, and shows concise but good error handling on failure paths.

[elithrar]

/bonk validate this is correct re: “always returning HTTP 200” - reference this claim

[ask-bonk]

All changes committed. Here is a summary of what was done:

Changes made

server-side-validation.mdx

Basic validation examples -- Added a TypeScript tab as the first (primary) tab with:

• JSON variant: fully typed validateTurnstile function with Promise<TurnstileResponse> return type, proper as TurnstileResponse assertion on response.json(), and conditional spread for optional remoteip
• Form Data variant: fully typed with FormData, proper null-guard for the token (typeof token !== "string"), uses ?? (nullish coalescing) instead of ||, and falls back to undefined for missing IP (instead of sending "unknown" to the API)

Advanced validation techniques -- Wrapped both the retry and enhanced-validation code blocks in <Tabs> with TypeScript as primary:

• Retry: added TurnstileResponse return type, typed all parameters, added unreachable-return comment to satisfy the compiler
• Enhanced validation: introduced ValidationOptions interface and ValidationResult discriminated union type, uses Date.now() instead of new Date() for correct numeric subtraction, non-null assertion on challenge_ts justified by the success === true guard above it

Full implementation example -- Wrapped in <Tabs> with TypeScript as primary:

• Full class with private readonly fields, ValidateOptions and ValidateResult types
• error instanceof DOMException guard for AbortError (more robust than bare .name check)
• MAX_TOKEN_LENGTH constant instead of magic number

testing.mdx

• Added Tabs, TabItem to the import statement
• Wrapped the server-side testing snippet in <Tabs> with TypeScript as primary, adding string type annotation and non-null assertion for the production env var

Code quality notes

All TypeScript examples were reviewed by the code review agent and confirmed:

• Types are correct and match the TurnstileResponse interface defined on the page
• Error handling is idiomatic (try/catch with typed fallback returns)
• as TurnstileResponse on response.json() is the standard pattern (returns any)
• All <Tabs>/<TabItem> tags are balanced across both files

github run

[elithrar]

The Turnstile team does not want to document additional fields.

[github-actions]

CI run failed: build logs

[eherot]

1. A note under the table indicating that additional fields may be present and should be ignored would be helpful for us Java developers using the Jackson ObjectMapper with its "strict by default" deserializer.
2. In case it's helpful, the tokenId field appeared along with the timeout-or-duplicate error.