widget mgmt pt 1

Author: patriciasantaana

src/content/docs/turnstile/get-started/index.mdx

@@ -1,77 +1,91 @@
 ---
-title: Get started with Turnstile
+title: Get started
 pcx_content_type: get-started
 sidebar:
   order: 4
-  group:
-    label: Get started
+---
+
+
+import { GlossaryTooltip, Render, LinkButton } from "~/components"
+
+This guide will get you started on setting up the Turnstile widget to protect your website from bots while maintaining a seamless user experience.
+
+## Prerequisites
+
+Before you begin, you must have: 
+
+- A Cloudflare account
+- A website or web application to protect
+- Basic knowledge of HTML and your preferred server-side language
 
 ---
 
-import { GlossaryTooltip, Render } from "~/components"
+## Implementation
+
+Implementing Turnstile involves two essential components that work together:
+
+1. **Client-side**: Embed the widget
+
+    Add the Turnstile widget to your webpage to challenge visitors and generate verification tokens.
 
-This guide will get you started on setting up the Turnstile widget.
+2. **Server-side**: Validate the response
 
-If you are currently using a <GlossaryTooltip term="CAPTCHA">CAPTCHA</GlossaryTooltip> service, you can copy and paste our script wherever you have deployed the existing script today.
+    Verify the tokens on your server using the Siteverify API to ensure they are authentic and have not been tampered with.
 
-## Get a sitekey and secret key
+Refer to [Implementation path](/turnstile/get-started/#implementation-path) below for guidance on how to implement Turnstile to your website.
+
+---
+
+## Key security requirements
+
+Mandatory server-side validation
+
+- It is critical to enforce Turnstile tokens with the Siteverify API. The Turnstile token could be invalid, expired, or already redeemed. Not verifying the token will leave major vulnerabilities in your implementation. You must call Siteverify to complete your Turnstile configuration. Otherwise, it is incomplete and will result in zeroes for token validation when viewing your metrics in [Turnstile Analytics](/turnstile/turnstile-analytics/).
+
+Token lifecycle
+
+- Tokens expire after 300 seconds (5 minutes). Each token can only be validated once. Expired or used tokens must be replaced with fresh challenges.
+
+---
 
-To start using the Turnstile widget, you will need to obtain a <GlossaryTooltip term="sitekey">sitekey</GlossaryTooltip> and a <GlossaryTooltip term="secret key">secret key</GlossaryTooltip>. The sitekey and secret key are always associated with one widget and cannot be reused for other widgets.
+## Implementation path
 
-The sitekey is public and used to invoke the Turnstile widget on your site.
+Follow the steps below to implement Turnstile.
 
-The sitekey and secret key are generated upon the creation of a widget, allowing communication between your site and Cloudflare to verify responses for a solved challenge from Turnstile. Make sure you keep the secret key safe for security reasons.
+### 1. Create your widget
 
-:::note
+First, you must create a Turnstile widget to get your sitekey and secret key.
 
-You can find special sitekeys to be used for testing in the [testing](/turnstile/troubleshooting/testing/) section.
-:::
+Select your preferred method:
 
-### New sites
 
-1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/?to=/:account/turnstile) and select your account.
-2. Go to **Turnstile**.
-3. Select **Add widget** and fill out the site name and [your website's hostname or select from your existing websites](/turnstile/concepts/hostname-management/) on Cloudflare.
-4. Select the widget mode.
-5. (Optional) Opt in for [pre-clearance support](/turnstile/concepts/pre-clearance-support/).
-6. Copy your sitekey and secret key.
+<LinkButton href="/">Cloudflare dashboard</LinkButton>
 
-### Existing sites
+<LinkButton href="/">API</LinkButton>
 
-1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/?to=/:account/turnstile) and select your account.
-2. Go to **Turnstile**.
-3. In the widget overview, select **Settings**.
-4. Confirm the [hostnames](/turnstile/concepts/hostname-management/) configured.
-5. (Optional) Opt in for [pre-clearance support](/turnstile/concepts/pre-clearance-support/).
-6. Copy your sitekey and secret key.
+<LinkButton href="/">Terraform</LinkButton>
 
-## Add the Turnstile widget to your site
+### 2. Embed the widget
 
-To add the Turnstile widget:
+Add the Turnstile widget to your webpage forms and applications.
 
-1. Insert the Turnstile script snippet in your HTML's `<head>` element:
+Refer to [Embed the widget] to learn more about implicit and explicit rendering methods
 
-<div>
+### 3. Validate tokens
 
-```html
-<script src="https://challenges.cloudflare.com/turnstile/v0/api.js" async defer></script>
-```
+Implement server-side validation to verify the tokens generated by your widgets.
 
-</div>
+Refer to [Validate the tokens] to secure your implementation with proper token verification.
 
-2. [Render the client-side integration](/turnstile/get-started/client-side-rendering/)
+## Additional implementation options
 
-   - [Explicit rendering](/turnstile/get-started/client-side-rendering/#explicitly-render-the-turnstile-widget)
-   - [Implicit rendering](/turnstile/get-started/client-side-rendering/#implicitly-render-the-turnstile-widget)
+### Mobile configuration
 
-## Validate the server-side response
+Special considerations are necessary for mobile applications and WebView implementations. Refer to [Mobile implementation]() for more information on mobile application integration.
 
-<Render file="siteverify-warning" />
+### Migration from other CAPTCHAs
 
-After you have installed the Turnstile widget on your site, you must configure your server to validate the Turnstile response.
-Refer to [Server-side validation](/turnstile/get-started/server-side-validation/).
+If you are currently using reCAPTCHA, hCaptcha, or another CAPTCHA service, Turnstile can be a drop-in replacement. You can copy and paste our script wherever you have deployed the existing script today.
 
-:::note
+Refer to [Migration](/turnstile/migration/) for step-by-step migration guidance from other CAPTCHA services.
 
-Rendering the client-side integration & validating the server-side response are both necessary to allow Turnstile to function properly.
-:::

src/content/docs/turnstile/get-started/client-side-rendering.mdx renamed to src/content/docs/turnstile/get-started/widget-management/client-side-rendering.mdx

@@ -2,7 +2,7 @@
 title: Client-side rendering
 pcx_content_type: get-started
 sidebar:
-  order: 1
+  order: 2
 ---
 
 import { Render } from "~/components";

src/content/docs/turnstile/get-started/widget-management/index.mdx

@@ -0,0 +1,25 @@
+---
+title: Widget management
+pcx_content_type: get-started
+sidebar:
+  order: 1
+  label: Overview
+
+---
+
+Learn how to create, configure, and manage your Turnstile widgets using the Cloudflare dashboard, API, or Terraform.
+
+## Overview
+
+Turnstile widgets are the foundation of your bot protection implementation. 
+
+Every widget has:
+
+  - **Sitekey**: Public identifier used in your webpage code
+  - **Secret Key**: Private key used for server-side validation
+  - **Configuration**: Mode, hostnames, appearance settings, and other options
+
+:::note[Important]
+Regardless of how you create and manage your widgets, you will still need to embed them on your webpage and validate tokens on your server.
+:::
+

src/content/docs/turnstile/get-started/server-side-validation.mdx renamed to src/content/docs/turnstile/get-started/widget-management/server-side-validation.mdx

@@ -2,7 +2,7 @@
 title: Server-side validation
 pcx_content_type: get-started
 sidebar:
-  order: 2
+  order: 3
 ---
 
 import { GlossaryTooltip, Render, TabItem, Tabs } from "~/components";