[Turnstile] FAQ to Docs (#25600)

patriciasantaana · web-flow · commit ac3c367a92ff · 2025-10-03T13:30:58.000-07:00
* FAQ to Docs

* fixes

* wording

* redirect

* feedback
diff --git a/public/__redirects b/public/__redirects
@@ -1632,6 +1632,7 @@
 /turnstile/get-started/supported-browsers/ /cloudflare-challenges/reference/supported-browsers/ 301
 /turnstile/troubleshooting/troubleshooting-faqs/ /turnstile/frequently-asked-questions/#troubleshooting 301
 /turnstile/tutorials/protecting-your-payment-form-from-attackers-bots-using-turnstile/ /developer-spotlight/ 301
+/turnstile/frequently-asked-questions/ /turnstile/ 301
 
 # waf
 /waf/about/ /waf/concepts/ 301
diff --git a/src/content/docs/cloudflare-challenges/troubleshooting/index.mdx b/src/content/docs/cloudflare-challenges/troubleshooting/index.mdx
@@ -13,6 +13,7 @@ import { Render } from "~/components"
 ### Proxied hostnames
 
 <Render file="proxied-hostnames" product="turnstile" />
+
 <Render file="challenge-behavior" product="turnstile" />
 
 ### Deprecated browser support
diff --git a/src/content/docs/turnstile/concepts/widget.mdx b/src/content/docs/turnstile/concepts/widget.mdx
@@ -9,6 +9,8 @@ import { GlossaryTooltip, Render } from "~/components";
 
 Every instance of Turnstile belongs to a Turnstile widget. It is configured on a per-widget level. Every widget has a mode, a label, a <GlossaryTooltip term="sitekey">sitekey</GlossaryTooltip>, and a <GlossaryTooltip term="secret key">secret key</GlossaryTooltip>.
 
+Turnstile is hosted under `challenges.cloudflare.com`. Your application will connect to this origin.
+
 ## Widget components
 
 <Render file="widget-components" product="turnstile" />
diff --git a/src/content/docs/turnstile/frequently-asked-questions.mdx b/src/content/docs/turnstile/frequently-asked-questions.mdx
diff --git a/src/content/docs/turnstile/get-started/client-side-rendering/index.mdx b/src/content/docs/turnstile/get-started/client-side-rendering/index.mdx
@@ -441,6 +441,12 @@ For a complete list of configuration options, refer to [Widget configurations](/
 
 ---
 
+## Limitations
+
+Turnstile is designed to function only on pages using `http://` or `https://` URI schemes. Other protocols, such as `file://`, are not supported for embedding the widget.
+
+---
+
 ## Security requirements
 
 <Render file="security-requirements" product="turnstile" />
diff --git a/src/content/docs/turnstile/get-started/index.mdx b/src/content/docs/turnstile/get-started/index.mdx
@@ -39,6 +39,8 @@ Implementing Turnstile involves two essential components that work together:
 
    Verify the tokens on your server using the Siteverify API to ensure they are authentic and have not been tampered with.
 
+Turnstile is designed to be an independent service. You can use Turnstile on any website, regardless of whether it is proxied through the Cloudflare network. This allows for flexible deployment across multi-cloud environments, on-premises infrastructure, or sites using other CDNs. The client-side widget and server-side validation steps are completely self-contained.
+
 Refer to [Implementation](#implementation) below for guidance on how to implement Turnstile on your website.
 
 ---
diff --git a/src/content/docs/turnstile/get-started/server-side-validation.mdx b/src/content/docs/turnstile/get-started/server-side-validation.mdx
@@ -52,6 +52,10 @@ The API accepts both `application/x-www-form-urlencoded` and `application/json`
 - Single use: Each token can only be validated once
 - Automatic expiry: Tokens automatically expire and cannot be reused
 
+The validation token issued by Turnstile is valid for five minutes. If a user submits the form after this period, the token is considered expired. In this scenario, the server-side verification API will return a failure, and the `error-codes` field in the response will include `timeout-or-duplicate`. 
+
+To ensure a successful validation, the visitor must initiate the request and submit the token to your backend within the five-minute window. Otherwise, the Turnstile widget needs to be refreshed to generate a new token. This can be done using the `turnstile.reset` function.
+
 ---
 
 ## Basic validation examples
@@ -684,6 +688,7 @@ if (result.success) {
 - Check additional fields. Validate the action and hostname when specified.
 - Monitor for abuse and log failed validations and unusual patterns.
 - Use HTTPS. Always validate over secure connections.
+- Only call the Siteverify API in your backend environment. If you expose the secret key in the front-end client code to call Siteverify, attackers can bypass the security check. Ensure that your client-side code sends the validation token to your backend, and that your backend is the sole caller of the Siteverify API.
 
 ### Performance
 
diff --git a/src/content/docs/turnstile/reference/supported-browsers.mdx b/src/content/docs/turnstile/reference/supported-browsers.mdx
@@ -1,8 +1,8 @@
 ---
-pcx_content_type: concept
+pcx_content_type: reference
 title: Supported browsers
 external_link: /cloudflare-challenges/reference/supported-browsers/
 sidebar:
-  order: 3
+  order: 4
 
 ---
diff --git a/src/content/docs/turnstile/reference/supported-languages.mdx b/src/content/docs/turnstile/reference/supported-languages.mdx
@@ -2,7 +2,7 @@
 title: Supported languages
 pcx_content_type: reference
 sidebar:
-  order: 2
+  order: 3
 
 ---
 
diff --git a/src/content/docs/turnstile/reference/turnstile-privacy-addendum.mdx b/src/content/docs/turnstile/reference/turnstile-privacy-addendum.mdx
@@ -0,0 +1,8 @@
+---
+pcx_content_type: reference
+title: Turnstile Privacy Addendum
+external_link: https://www.cloudflare.com/turnstile-privacy-policy/
+sidebar:
+  order: 2
+
+---
diff --git a/src/content/docs/turnstile/reference/workers-templates/index.mdx b/src/content/docs/turnstile/reference/workers-templates/index.mdx
diff --git a/src/content/docs/turnstile/reference/workers-templates/price-scraping.mdx b/src/content/docs/turnstile/reference/workers-templates/price-scraping.mdx
diff --git a/src/content/docs/turnstile/troubleshooting/client-side-errors/error-codes.mdx b/src/content/docs/turnstile/troubleshooting/client-side-errors/error-codes.mdx
@@ -45,3 +45,9 @@ Error code family `300***` and `600***` (e.g. "`600010: The generic_challenge_fa
 You can troubleshoot these error codes using the following recommendations:
 
 <Render file="troubleshooting-steps" product="turnstile" />
+
+## Error code `401`
+
+Turnstile may occasionally generate a `401` Unauthorized error in your browser console during a security check. This is not typically a problem with your implementation. This error often occurs when the widget attempts to request a [Private Access Token](/cloudflare-challenges/reference/private-access-tokens/) that your device or browser does not support yet. 
+
+You can generally safely ignore the `401` error, as it is an expected part of Turnstile's underlying Challenge Platform workflow. If the widget is successfully resolving and you are receiving a token, no action is required.
diff --git a/src/content/docs/turnstile/troubleshooting/feedback-reports.mdx b/src/content/docs/turnstile/troubleshooting/feedback-reports.mdx
@@ -8,6 +8,13 @@ sidebar:
 
 When Cloudflare detects that a challenge has failed or the user cannot be verified on a page with Turnstile, the user will encounter an [error](/turnstile/concepts/widget/#error-states) on the widget and may be asked to send feedback on the issue that they have encountered by choosing one of the options listed.
 
+When debugging or submitting a feedback report for an unresolved issue, you must provide the Ray ID or QR code associated with the challenge. These identifiers are essential for Cloudflare Support to trace the specific event.
+
+To obtain these identifiers:
+
+1. Ray ID: Find the Ray ID displayed at the end of the Challenge Page. The RayID is collected by the feedback report.
+2. QR Code: Click the success, failure, or spinner logo on the Turnstile widget four times. This action will reveal the unique QR code for that challenge instance.
+
 :::note
 
 Currently, feedback submitted via the feedback form is sent directly to Cloudflare and used for improvements on the Turnstile user experience.
