Cloudflare Turnstile is a bot-mitigation solution that verifies that visitors are real without requiring them to solve a CAPTCHA. The eCDN Turnstile endpoints let you manage Turnstile widgets for your Commerce Cloud storefronts—creating, listing, updating, and deleting widgets programmatically.
Each widget is identified by a sitekey (the public key embedded in your storefront HTML) and has a corresponding secret (used server-side to validate challenge responses). The API returns the secret so that you can store it in your application’s server-side configuration.
For general eCDN concepts and the zones API, see CDN Zones.
A widget operates in one of three modes:
| Mode | Behavior |
|---|---|
managed | Cloudflare determines the optimal challenge type (recommended for most use cases). |
non-interactive | A non-interactive challenge runs automatically without user action. |
invisible | The challenge runs entirely in the background with no visible widget rendered. |
Widgets are scoped to the realm and environment derived from the organization ID. For example, a GET request from f_ecom_bcxj_prd returns only production widgets for realm bcxj.
Each widget is associated with one or more domains (hostnames) where it can be presented. Only requests that originate from a listed domain pass validation. Update the domain list as hostnames are added to or removed from your storefront.
All Turnstile endpoints require an OAuth 2.0 bearer token with the sfcc.cdn-zones.rw scope.
The Turnstile endpoints are relative to the following base URL:
https://{shortCode}.api.commercecloud.salesforce.com/cdn/zones/v1/organizations/{organizationId}
Retrieves all Turnstile widgets for the requesting instance. Results are paginated and cached for 5 minutes.
GET /organizations/{organizationId}/turnstile/widgets
Query parameters:
| Parameter | Required | Default | Description |
|---|---|---|---|
name | No | — | Filter by widget name (exact match). |
offset | No | 0 | Pagination offset. |
limit | No | 25 | Results per page (1–50). |
A 200 OK response includes the following pagination headers:
SFDC-Pagination-OffsetSFDC-Pagination-LimitSFDC-Pagination-Total-CountSFDC-Pagination-Result-CountExample response body:
1{
2 "data": [
3 {
4 "sitekey": "0x4AAAAAAAAbCd1eFgHiJkLm",
5 "name": "checkout-widget",
6 "mode": "managed",
7 "domains": ["shop.example.com", "www.example.com"],
8 "bot_fight_mode": false,
9 "region": "world",
10 "offlabel": false,
11 "clearance_level": "interactive",
12 "created_on": "2026-01-15T12:00:00Z",
13 "modified_on": "2026-02-20T08:30:00Z",
14 "secret": "0x4AAAAAAAAbCd1eFgHiJkLm_secretvalue"
15 }
16 ]
17}Creates a new Cloudflare Turnstile widget for the requesting instance. Each instance allows up to 5,000 widgets.
POST /organizations/{organizationId}/turnstile/widgets
Required attributes:
| Attribute | Type | Description |
|---|---|---|
name | string | Logical widget name. |
domains | array of strings | Hostnames allowed to present the widget. At least one required. |
mode | string | Widget mode: managed, non-interactive, or invisible. |
Example request body:
1{
2 "name": "checkout",
3 "domains": ["shop.example.com", "www.example.com"],
4 "mode": "managed"
5}A 201 Created response returns the new widget, including its secret:
1{
2 "data": {
3 "sitekey": "0x4AAAAAAAAbCd1eFgHiJkLm",
4 "name": "checkout-widget",
5 "mode": "managed",
6 "domains": ["shop.example.com", "www.example.com"],
7 "bot_fight_mode": false,
8 "region": "world",
9 "offlabel": false,
10 "clearance_level": "interactive",
11 "created_on": "2026-01-15T12:00:00Z",
12 "modified_on": "2026-01-15T12:00:00Z",
13 "secret": "0x4AAAAAAAAbCd1eFgHiJkLm_secretvalue"
14 }
15}The response includes the secret. Store it securely in your server-side configuration—you need it to validate Turnstile challenge responses.
Note
Retrieves the full configuration of a widget by sitekey, including the shared secret.
GET /organizations/{organizationId}/turnstile/widgets/{sitekey}
Path parameters:
| Parameter | Description |
|---|---|
sitekey | The unique identifier of the widget. |
A 200 OK response returns the widget. The endpoint returns 404 Not Found if the widget doesn’t exist.
1{
2 "data": {
3 "sitekey": "0x4AAAAAAAAbCd1eFgHiJkLm",
4 "name": "checkout-widget",
5 "mode": "managed",
6 "domains": ["shop.example.com", "www.example.com"],
7 "bot_fight_mode": false,
8 "region": "world",
9 "offlabel": false,
10 "clearance_level": "interactive",
11 "created_on": "2026-01-15T12:00:00Z",
12 "modified_on": "2026-02-20T08:30:00Z",
13 "secret": "0x4AAAAAAAAbCd1eFgHiJkLm_secretvalue"
14 }
15}Updates the domains and/or mode of an existing widget.
PUT /organizations/{organizationId}/turnstile/widgets/{sitekey}
Path parameters:
| Parameter | Description |
|---|---|
sitekey | The unique identifier of the widget to update. |
Optional attributes (at least one required):
| Attribute | Type | Description |
|---|---|---|
domains | array of strings | Replacement list of allowed hostnames. |
mode | string | New widget mode: managed, non-interactive, or invisible. |
Example request body:
1{
2 "domains": ["shop.example.com", "www.example.com", "checkout.example.com"],
3 "mode": "invisible"
4}A 200 OK response returns the updated widget. The endpoint returns 404 Not Found if the widget doesn’t exist, and 400 Bad Request if the request exceeds the Cloudflare hostname limit for the widget.
Deletes an existing widget. This operation is irreversible and immediately invalidates the sitekey and secret.
DELETE /organizations/{organizationId}/turnstile/widgets/{sitekey}
Path parameters:
| Parameter | Description |
|---|---|
sitekey | The unique identifier of the widget to delete. |
Query parameters:
| Parameter | Required | Default | Description |
|---|---|---|---|
forceProduction | No | false | Must be true to delete a production widget. Without this flag, deleting a production widget returns 403 Forbidden. |
dryRun | No | false | When true, validates the request without performing the deletion. |
A successful deletion returns 204 No Content. The endpoint returns 404 Not Found if the widget doesn’t exist, and 403 Forbidden if you attempt to delete a production widget without forceProduction=true.
Production widgets (environment = prd) require an explicit forceProduction=true. Use dryRun=true to validate parameters before committing to deletion. Post-deletion verification runs automatically to confirm removal.
Note
All Turnstile endpoints return errors in application/problem+json format:
1{
2 "title": "Short description of the error",
3 "type": "ErrorType",
4 "detail": "Additional context about what went wrong"
5}| Status Code | Meaning |
|---|---|
400 | Bad request—invalid input, name too long, hostname limit exceeded, and so on. |
401 | Unauthorized—missing or invalid bearer token. |
403 | Forbidden—insufficient scope, or production deletion without the force flag. |
404 | Not found—a widget with the given sitekey doesn’t exist. |
500 | Internal server error. |
A typical workflow:
POST /turnstile/widgets with your desired name, domains, and mode.sitekey and secret from the response to your Managed Runtime application’s .env file. For the exact environment variables and configuration, see steps 2(a) and 2(b) in the Storefront Next One-Click Checkout guide.PUT /turnstile/widgets/{sitekey} to keep the domain list in sync.GET /turnstile/widgets/{sitekey}, which isn’t cached.name after creation. To rename a widget, delete and recreate it.To choose a mode, use this guidance:
managed (recommended) for most storefronts—Cloudflare picks the optimal challenge.invisible for a seamless experience where no widget is shown.non-interactive when you want the challenge to run automatically without a visible puzzle but still show the widget.
j