---
title: Rotate Secret for a Turnstile Widget
---

[Skip to content](#_top)

[API Reference](https://developers.cloudflare.com/api/python)

[Turnstile](https://developers.cloudflare.com/api/python/resources/turnstile)

[Widgets](https://developers.cloudflare.com/api/python/resources/turnstile/subresources/widgets)

Copy Markdown

Open in **Claude**Open in **ChatGPT**Open in **Cursor**

---

**Copy Markdown****View as Markdown**

# Rotate Secret for a Turnstile Widget

turnstile.widgets.rotate\_secret(strsitekey, WidgetRotateSecretParams\*\*kwargs) -> [Widget](<https://developers.cloudflare.com/api/python/resources/turnstile#(resource)%20turnstile.widgets%20%3E%20(model)%20widget%20%3E%20(schema)>)

POST/accounts/{account\_id}/challenges/widgets/{sitekey}/rotate\_secret

Generates 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

<details>

<summary>API Token</summary>



The preferred authorization scheme for interacting with the Cloudflare API. <a href="https://developers.cloudflare.com/fundamentals/api/get-started/create-token/">Create a token</a>.

**Example:**<code>Authorization: Bearer Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY</code>

</details>

<details>

<summary>API Email + API Key</summary>



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

**Example:**<code>X-Auth-Email: user@example.com</code>

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

**Example:**<code>X-Auth-Key: 144c9defac04969c7bfad8efaa8ea194</code>

</details>

##### Accepted Permissions (at least one required)

`Turnstile Sites Write``Account Settings Write`

##### ParametersExpand Collapse

account\_id: str

Identifier

maxLength32

[Link to this property](<#(resource)%20turnstile.widgets%20%3E%20(method)%20rotate_secret%20%3E%20(params)%20default%20%3E%20(param)%20account_id%20%3E%20(schema)>)

sitekey: str

Unique identifier for a Turnstile widget.

maxLength32

[Link to this property](<#(resource)%20turnstile.widgets%20%3E%20(method)%20rotate_secret%20%3E%20(params)%20default%20%3E%20(param)%20sitekey%20%3E%20(schema)>)

invalidate\_immediately: Optional\[[bool](<https://developers.cloudflare.com/api/python/resources/turnstile/subresources/widgets/methods/rotate_secret#(resource)%20turnstile.widgets%20%3E%20(method)%20rotate_secret%20%3E%20(params)%20default%20%3E%20(param)%20invalidate_immediately%20%3E%20(schema)>)]

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.

[Link to this property](<#(resource)%20turnstile.widgets%20%3E%20(method)%20rotate_secret%20%3E%20(params)%20default%20%3E%20(param)%20invalidate_immediately%20%3E%20(schema)>)

##### ReturnsExpand Collapse

<details>

<summary>

class Widget: …

A Turnstile widget’s detailed configuration

</summary>

bot\_fight\_mode: bool

If bot\_fight\_mode is set to <code>true</code>, Cloudflare issues computationally expensive challenges in response to malicious bots (ENT only).

<a href="#(resource)%20turnstile.widgets%20%3E%20(model)%20widget%20%3E%20(schema)%20%3E%20(property)%20bot_fight_mode">Link to this property</a>

<details>

<summary>

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

</summary>

One of the following:

"no\_clearance"

<a href="#(resource)%20turnstile.widgets%20%3E%20(model)%20widget%20%3E%20(schema)%20%3E%20(property)%20clearance_level%20%3E%20(member)%200">Link to this property</a>

"jschallenge"

<a href="#(resource)%20turnstile.widgets%20%3E%20(model)%20widget%20%3E%20(schema)%20%3E%20(property)%20clearance_level%20%3E%20(member)%201">Link to this property</a>

"managed"

<a href="#(resource)%20turnstile.widgets%20%3E%20(model)%20widget%20%3E%20(schema)%20%3E%20(property)%20clearance_level%20%3E%20(member)%202">Link to this property</a>

"interactive"

<a href="#(resource)%20turnstile.widgets%20%3E%20(model)%20widget%20%3E%20(schema)%20%3E%20(property)%20clearance_level%20%3E%20(member)%203">Link to this property</a>

</details>

<a href="#(resource)%20turnstile.widgets%20%3E%20(model)%20widget%20%3E%20(schema)%20%3E%20(property)%20clearance_level">Link to this property</a>

created\_on: datetime

When the widget was created.

formatdate-time

<a href="#(resource)%20turnstile.widgets%20%3E%20(model)%20widget%20%3E%20(schema)%20%3E%20(property)%20created_on">Link to this property</a>

domains: List\[<a href="https://developers.cloudflare.com/api/python/resources/turnstile#(resource)%20turnstile.widgets%20%3E%20(model)%20widget_domain%20%3E%20(schema)">WidgetDomain</a>]

maxLength10

<a href="#(resource)%20turnstile.widgets%20%3E%20(model)%20widget%20%3E%20(schema)%20%3E%20(property)%20domains">Link to this property</a>

ephemeral\_id: bool

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

<a href="#(resource)%20turnstile.widgets%20%3E%20(model)%20widget%20%3E%20(schema)%20%3E%20(property)%20ephemeral_id">Link to this property</a>

<details>

<summary>

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

Widget Mode

</summary>

One of the following:

"non-interactive"

<a href="#(resource)%20turnstile.widgets%20%3E%20(model)%20widget%20%3E%20(schema)%20%3E%20(property)%20mode%20%3E%20(member)%200">Link to this property</a>

"invisible"

<a href="#(resource)%20turnstile.widgets%20%3E%20(model)%20widget%20%3E%20(schema)%20%3E%20(property)%20mode%20%3E%20(member)%201">Link to this property</a>

"managed"

<a href="#(resource)%20turnstile.widgets%20%3E%20(model)%20widget%20%3E%20(schema)%20%3E%20(property)%20mode%20%3E%20(member)%202">Link to this property</a>

</details>

<a href="#(resource)%20turnstile.widgets%20%3E%20(model)%20widget%20%3E%20(schema)%20%3E%20(property)%20mode">Link to this property</a>

modified\_on: datetime

When the widget was modified.

formatdate-time

<a href="#(resource)%20turnstile.widgets%20%3E%20(model)%20widget%20%3E%20(schema)%20%3E%20(property)%20modified_on">Link to this property</a>

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

<a href="#(resource)%20turnstile.widgets%20%3E%20(model)%20widget%20%3E%20(schema)%20%3E%20(property)%20name">Link to this property</a>

offlabel: bool

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

<a href="#(resource)%20turnstile.widgets%20%3E%20(model)%20widget%20%3E%20(schema)%20%3E%20(property)%20offlabel">Link to this property</a>

<details>

<summary>

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

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

</summary>

One of the following:

"world"

<a href="#(resource)%20turnstile.widgets%20%3E%20(model)%20widget%20%3E%20(schema)%20%3E%20(property)%20region%20%3E%20(member)%200">Link to this property</a>

"china"

<a href="#(resource)%20turnstile.widgets%20%3E%20(model)%20widget%20%3E%20(schema)%20%3E%20(property)%20region%20%3E%20(member)%201">Link to this property</a>

</details>

<a href="#(resource)%20turnstile.widgets%20%3E%20(model)%20widget%20%3E%20(schema)%20%3E%20(property)%20region">Link to this property</a>

secret: str

Secret key for this widget.

<a href="#(resource)%20turnstile.widgets%20%3E%20(model)%20widget%20%3E%20(schema)%20%3E%20(property)%20secret">Link to this property</a>

sitekey: str

Unique identifier for a Turnstile widget.

maxLength32

<a href="#(resource)%20turnstile.widgets%20%3E%20(model)%20widget%20%3E%20(schema)%20%3E%20(property)%20sitekey">Link to this property</a>

<details>

<summary>

deployed\_via: Optional\[Literal\["wrangler", "dashboard", "spin", 2 more]]

Origin that created this widget, recorded at creation time and immutable afterward. Server-derived from the create request; not client-settable. Omitted from the response for widgets created before this field existed.

</summary>

One of the following:

"wrangler"

<a href="#(resource)%20turnstile.widgets%20%3E%20(model)%20widget%20%3E%20(schema)%20%3E%20(property)%20deployed_via%20%3E%20(member)%200">Link to this property</a>

"dashboard"

<a href="#(resource)%20turnstile.widgets%20%3E%20(model)%20widget%20%3E%20(schema)%20%3E%20(property)%20deployed_via%20%3E%20(member)%201">Link to this property</a>

"spin"

<a href="#(resource)%20turnstile.widgets%20%3E%20(model)%20widget%20%3E%20(schema)%20%3E%20(property)%20deployed_via%20%3E%20(member)%202">Link to this property</a>

"api"

<a href="#(resource)%20turnstile.widgets%20%3E%20(model)%20widget%20%3E%20(schema)%20%3E%20(property)%20deployed_via%20%3E%20(member)%203">Link to this property</a>

"unknown"

<a href="#(resource)%20turnstile.widgets%20%3E%20(model)%20widget%20%3E%20(schema)%20%3E%20(property)%20deployed_via%20%3E%20(member)%204">Link to this property</a>

</details>

<a href="#(resource)%20turnstile.widgets%20%3E%20(model)%20widget%20%3E%20(schema)%20%3E%20(property)%20deployed_via">Link to this property</a>

<details>

<summary>

last\_modified\_via: Optional\[Literal\["wrangler", "dashboard", "spin", 2 more]]

Origin of the most recent mutation (create, update, delete, or secret rotation). Server-derived; not client-settable. Omitted for widgets last mutated before this field existed.

</summary>

One of the following:

"wrangler"

<a href="#(resource)%20turnstile.widgets%20%3E%20(model)%20widget%20%3E%20(schema)%20%3E%20(property)%20last_modified_via%20%3E%20(member)%200">Link to this property</a>

"dashboard"

<a href="#(resource)%20turnstile.widgets%20%3E%20(model)%20widget%20%3E%20(schema)%20%3E%20(property)%20last_modified_via%20%3E%20(member)%201">Link to this property</a>

"spin"

<a href="#(resource)%20turnstile.widgets%20%3E%20(model)%20widget%20%3E%20(schema)%20%3E%20(property)%20last_modified_via%20%3E%20(member)%202">Link to this property</a>

"api"

<a href="#(resource)%20turnstile.widgets%20%3E%20(model)%20widget%20%3E%20(schema)%20%3E%20(property)%20last_modified_via%20%3E%20(member)%203">Link to this property</a>

"unknown"

<a href="#(resource)%20turnstile.widgets%20%3E%20(model)%20widget%20%3E%20(schema)%20%3E%20(property)%20last_modified_via%20%3E%20(member)%204">Link to this property</a>

</details>

<a href="#(resource)%20turnstile.widgets%20%3E%20(model)%20widget%20%3E%20(schema)%20%3E%20(property)%20last_modified_via">Link to this property</a>

</details>

[Link to this property](<#(resource)%20turnstile.widgets%20%3E%20(model)%20widget%20%3E%20(schema)>)

### Rotate Secret for a Turnstile Widget

Python

HTTPTypeScriptPythonGoTerraform

```
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)
```

200 example

```
{
  "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",
    "deployed_via": "wrangler",
    "last_modified_via": "dashboard"
  }
}
```

##### Returns Examples

200 example

```
{
  "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",
    "deployed_via": "wrangler",
    "last_modified_via": "dashboard"
  }
}
```