--- title: Update 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** # Update a Turnstile Widget turnstile.widgets.update(strsitekey, WidgetUpdateParams\*\*kwargs) -> [Widget]() PUT/accounts/{account\_id}/challenges/widgets/{sitekey} Updates the configuration of a Turnstile widget. ##### 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 Write``Account Settings Write` ##### ParametersExpand Collapse account\_id: str Identifier maxLength32 [Link to this property](<#(resource)%20turnstile.widgets%20%3E%20(method)%20update%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)%20update%20%3E%20(params)%20default%20%3E%20(param)%20sitekey%20%3E%20(schema)>) domains: Sequence\[[WidgetDomain]()] maxLength10 [Link to this property](<#(resource)%20turnstile.widgets%20%3E%20(method)%20update%20%3E%20(params)%20default%20%3E%20(param)%20domains%20%3E%20(schema)>)

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

One of the following: "non-interactive" Link to this property "invisible" Link to this property "managed" Link to this property

[Link to this property](<#(resource)%20turnstile.widgets%20%3E%20(method)%20update%20%3E%20(params)%20default%20%3E%20(param)%20mode%20%3E%20(schema)>) 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 [Link to this property](<#(resource)%20turnstile.widgets%20%3E%20(method)%20update%20%3E%20(params)%20default%20%3E%20(param)%20name%20%3E%20(schema)>) bot\_fight\_mode: Optional\[[bool]()] If bot\_fight\_mode is set to `true`, Cloudflare issues computationally expensive challenges in response to malicious bots (ENT only). [Link to this property](<#(resource)%20turnstile.widgets%20%3E%20(method)%20update%20%3E%20(params)%20default%20%3E%20(param)%20bot_fight_mode%20%3E%20(schema)>)

clearance\_level: Optional\[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" Link to this property "jschallenge" Link to this property "managed" Link to this property "interactive" Link to this property

[Link to this property](<#(resource)%20turnstile.widgets%20%3E%20(method)%20update%20%3E%20(params)%20default%20%3E%20(param)%20clearance_level%20%3E%20(schema)>) ephemeral\_id: Optional\[[bool]()] Return the Ephemeral ID in /siteverify (ENT only). [Link to this property](<#(resource)%20turnstile.widgets%20%3E%20(method)%20update%20%3E%20(params)%20default%20%3E%20(param)%20ephemeral_id%20%3E%20(schema)>) offlabel: Optional\[[bool]()] Do not show any Cloudflare branding on the widget (ENT only). [Link to this property](<#(resource)%20turnstile.widgets%20%3E%20(method)%20update%20%3E%20(params)%20default%20%3E%20(param)%20offlabel%20%3E%20(schema)>)

region: Optional\[Literal\["world", "china"]] Region where this widget can be used. This cannot be changed after creation.

One of the following: "world" Link to this property "china" Link to this property

[Link to this property](<#(resource)%20turnstile.widgets%20%3E%20(method)%20update%20%3E%20(params)%20default%20%3E%20(param)%20region%20%3E%20(schema)>) ##### 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). Link to this property

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" Link to this property "jschallenge" Link to this property "managed" Link to this property "interactive" Link to this property

Link to this property created\_on: datetime When the widget was created. formatdate-time Link to this property domains: List\[WidgetDomain] maxLength10 Link to this property ephemeral\_id: bool Return the Ephemeral ID in /siteverify (ENT only). Link to this property

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

One of the following: "non-interactive" Link to this property "invisible" Link to this property "managed" Link to this property

Link to this property modified\_on: datetime When the widget was modified. formatdate-time Link to this property 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 Link to this property offlabel: bool Do not show any Cloudflare branding on the widget (ENT only). Link to this property

region: Literal\["world", "china"] Region where this widget can be used. This cannot be changed after creation.

One of the following: "world" Link to this property "china" Link to this property

Link to this property secret: str Secret key for this widget. Link to this property sitekey: str Unique identifier for a Turnstile widget. maxLength32 Link to this property

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.

One of the following: "wrangler" Link to this property "dashboard" Link to this property "spin" Link to this property "api" Link to this property "unknown" Link to this property

Link to this property

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.

One of the following: "wrangler" Link to this property "dashboard" Link to this property "spin" Link to this property "api" Link to this property "unknown" Link to this property

Link to this property

[Link to this property](<#(resource)%20turnstile.widgets%20%3E%20(model)%20widget%20%3E%20(schema)>) ### Update 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.update( sitekey="0x4AAF00AAAABn0R22HWm-YUc", account_id="023e105f4ecef8ad9ca31a8372d0c353", domains=["203.0.113.1", "cloudflare.com", "blog.example.com"], mode="invisible", name="blog.cloudflare.com login form", ) 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" } } ```