Skip to content
Cloudflare API
Start here
API Reference
Turnstile
Widgets

Rotate Secret for a Turnstile Widget

turnstile.widgets.rotate_secret(strsitekey, WidgetRotateSecretParams**kwargs) -> Widget
POST/accounts/{account_id}/challenges/widgets/{sitekey}/rotate_secret

Generate a new secret key for this widget. If invalidate_immediately is set to false, the previous secret remains valid for 2 hours.

Note that secrets cannot be rotated again during the grace period.

Security
API Token

The preferred authorization scheme for interacting with the Cloudflare API. Create a token.

Example:Authorization: Bearer Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY
API Email + API Key

The previous authorization scheme for interacting with the Cloudflare API, used in conjunction with a Global API key.

Example:X-Auth-Email: user@example.com

The previous authorization scheme for interacting with the Cloudflare API. When possible, use API tokens instead of Global API keys.

Example:X-Auth-Key: 144c9defac04969c7bfad8efaa8ea194
Accepted Permissions (at least one required)
Turnstile Sites WriteAccount Settings Write
ParametersExpand Collapse
account_id: str

Identifier

maxLength32
sitekey: str

Widget item identifier tag.

maxLength32
invalidate_immediately: Optional[bool]

If invalidate_immediately is set to false, the previous secret will remain valid for two hours. Otherwise, the secret is immediately invalidated, and requests using it will be rejected.

ReturnsExpand Collapse
class Widget: …

A Turnstile widget's detailed configuration

bot_fight_mode: bool

If bot_fight_mode is set to true, Cloudflare issues computationally expensive challenges in response to malicious bots (ENT only).

clearance_level: Literal["no_clearance", "jschallenge", "managed", "interactive"]

If Turnstile is embedded on a Cloudflare site and the widget should grant challenge clearance, this setting can determine the clearance level to be set

One of the following:
"no_clearance"
"jschallenge"
"managed"
"interactive"
created_on: datetime

When the widget was created.

formatdate-time
domains: List[WidgetDomain]
maxLength10
ephemeral_id: bool

Return the Ephemeral ID in /siteverify (ENT only).

mode: Literal["non-interactive", "invisible", "managed"]

Widget Mode

One of the following:
"non-interactive"
"invisible"
"managed"
modified_on: datetime

When the widget was modified.

formatdate-time
name: str

Human readable widget name. Not unique. Cloudflare suggests that you set this to a meaningful string to make it easier to identify your widget, and where it is used.

maxLength254
minLength1
offlabel: bool

Do not show any Cloudflare branding on the widget (ENT only).

region: Literal["world", "china"]

Region where this widget can be used. This cannot be changed after creation.

One of the following:
"world"
"china"
secret: str

Secret key for this widget.

sitekey: str

Widget item identifier tag.

maxLength32

Rotate Secret for a Turnstile Widget

import os
from cloudflare import Cloudflare

client = Cloudflare(
    api_token=os.environ.get("CLOUDFLARE_API_TOKEN"),  # This is the default and can be omitted
)
widget = client.turnstile.widgets.rotate_secret(
    sitekey="0x4AAF00AAAABn0R22HWm-YUc",
    account_id="023e105f4ecef8ad9ca31a8372d0c353",
)
print(widget.ephemeral_id)
{
  "errors": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "messages": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "success": true,
  "result": {
    "bot_fight_mode": false,
    "clearance_level": "interactive",
    "created_on": "2014-01-01T05:20:00.123123Z",
    "domains": [
      "203.0.113.1",
      "cloudflare.com",
      "blog.example.com"
    ],
    "ephemeral_id": false,
    "mode": "invisible",
    "modified_on": "2014-01-01T05:20:00.123123Z",
    "name": "blog.cloudflare.com login form",
    "offlabel": false,
    "region": "world",
    "secret": "0x4AAF00AAAABn0R22HWm098HVBjhdsYUc",
    "sitekey": "0x4AAF00AAAABn0R22HWm-YUc"
  }
}
Returns Examples
{
  "errors": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "messages": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "success": true,
  "result": {
    "bot_fight_mode": false,
    "clearance_level": "interactive",
    "created_on": "2014-01-01T05:20:00.123123Z",
    "domains": [
      "203.0.113.1",
      "cloudflare.com",
      "blog.example.com"
    ],
    "ephemeral_id": false,
    "mode": "invisible",
    "modified_on": "2014-01-01T05:20:00.123123Z",
    "name": "blog.cloudflare.com login form",
    "offlabel": false,
    "region": "world",
    "secret": "0x4AAF00AAAABn0R22HWm098HVBjhdsYUc",
    "sitekey": "0x4AAF00AAAABn0R22HWm-YUc"
  }
}