widgets

Creates, updates, deletes, gets or lists a widgets resource.

Overview

Name	widgets
Type	Resource
Id	cloudflare.turnstile.widgets

Fields

The following fields are returned by SELECT queries:

get

Turnstile Widget Details Response

Name	Datatype	Description
name	string	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. (example: blog.cloudflare.com login form)
ephemeral_id	boolean	Return the Ephemeral ID in /siteverify (ENT only).
bot_fight_mode	boolean	If bot_fight_mode is set to true, Cloudflare issues computationally expensive challenges in response to malicious bots (ENT only).
clearance_level	string	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 (no_clearance, jschallenge, managed, interactive) (example: interactive)
created_on	string (date-time)	When the widget was created. (example: 2014-01-01T05:20:00.123123Z)
domains	array
mode	string	Widget Mode (non-interactive, invisible, managed) (example: invisible)
modified_on	string (date-time)	When the widget was modified. (example: 2014-01-01T05:20:00.123123Z)
offlabel	boolean	Do not show any Cloudflare branding on the widget (ENT only).
region	string	Region where this widget can be used. This cannot be changed after creation. (world, china) (default: world)
secret	string	Secret key for this widget. (example: 0x4AAF00AAAABn0R22HWm098HVBjhdsYUc)
sitekey	string	Widget item identifier tag. (example: 0x4AAF00AAAABn0R22HWm-YUc)

list

List Turnstile Widgets

Name	Datatype	Description
name	string	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. (example: blog.cloudflare.com login form)
ephemeral_id	boolean	Return the Ephemeral ID in /siteverify (ENT only).
bot_fight_mode	boolean	If bot_fight_mode is set to true, Cloudflare issues computationally expensive challenges in response to malicious bots (ENT only).
clearance_level	string	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 (no_clearance, jschallenge, managed, interactive) (example: interactive)
created_on	string (date-time)	When the widget was created. (example: 2014-01-01T05:20:00.123123Z)
domains	array
mode	string	Widget Mode (non-interactive, invisible, managed) (example: invisible)
modified_on	string (date-time)	When the widget was modified. (example: 2014-01-01T05:20:00.123123Z)
offlabel	boolean	Do not show any Cloudflare branding on the widget (ENT only).
region	string	Region where this widget can be used. This cannot be changed after creation. (world, china) (default: world)
sitekey	string	Widget item identifier tag. (example: 0x4AAF00AAAABn0R22HWm-YUc)

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get	select	account_id, sitekey		Show a single challenge widget configuration.
list	select	account_id	page, per_page, order, direction, filter	Lists all turnstile widgets of an account.
create	insert	account_id, name, mode, domains	page, per_page, order, direction, filter	Lists challenge widgets.
update	replace	account_id, sitekey, name, mode, domains		Update the configuration of a widget.
delete	delete	account_id, sitekey		Destroy a Turnstile Widget.
rotate_secret	exec	account_id, sitekey		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.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
account_id	string	The Cloudflare account ID.
sitekey	string
direction	string
filter	string	Filter widgets by field using case-insensitive substring matching. Format: field:value Supported fields: - name - Filter by widget name (e.g., filter=name:login-form) - sitekey - Filter by sitekey (e.g., filter=sitekey:0x4AAA) Returns 400 Bad Request if the field is unsupported or format is invalid. An empty filter value returns all results.
order	string
page	number
per_page	number

SELECT examples

get

Show a single challenge widget configuration.

SELECT
name,
ephemeral_id,
bot_fight_mode,
clearance_level,
created_on,
domains,
mode,
modified_on,
offlabel,
region,
secret,
sitekey
FROM cloudflare.turnstile.widgets
WHERE account_id = '{{ account_id }}' -- required
AND sitekey = '{{ sitekey }}' -- required
;

list

Lists all turnstile widgets of an account.

SELECT
name,
ephemeral_id,
bot_fight_mode,
clearance_level,
created_on,
domains,
mode,
modified_on,
offlabel,
region,
sitekey
FROM cloudflare.turnstile.widgets
WHERE account_id = '{{ account_id }}' -- required
AND page = '{{ page }}'
AND per_page = '{{ per_page }}'
AND order = '{{ order }}'
AND direction = '{{ direction }}'
AND filter = '{{ filter }}'
;

INSERT examples

create

Lists challenge widgets.

INSERT INTO cloudflare.turnstile.widgets (
bot_fight_mode,
clearance_level,
domains,
ephemeral_id,
mode,
name,
offlabel,
region,
account_id,
page,
per_page,
order,
direction,
filter
)
SELECT 
{{ bot_fight_mode }},
'{{ clearance_level }}',
'{{ domains }}' /* required */,
{{ ephemeral_id }},
'{{ mode }}' /* required */,
'{{ name }}' /* required */,
{{ offlabel }},
'{{ region }}',
'{{ account_id }}',
'{{ page }}',
'{{ per_page }}',
'{{ order }}',
'{{ direction }}',
'{{ filter }}'
RETURNING
errors,
messages,
result,
result_info,
success
;

Manifest

# Description fields are for documentation purposes
- name: widgets
props:
  - name: account_id
    value: "{{ account_id }}"
    description: Required parameter for the widgets resource.
  - name: bot_fight_mode
    value: {{ bot_fight_mode }}
    description: |
      If bot_fight_mode is set to `true`, Cloudflare issues computationally expensive challenges in response to malicious bots (ENT only).
  - name: clearance_level
    value: "{{ clearance_level }}"
    description: |
      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
    valid_values: ['no_clearance', 'jschallenge', 'managed', 'interactive']
  - name: domains
    value:
      - "{{ domains }}"
  - name: ephemeral_id
    value: {{ ephemeral_id }}
    description: |
      Return the Ephemeral ID in /siteverify (ENT only).
  - name: mode
    value: "{{ mode }}"
    description: |
      Widget Mode
    valid_values: ['non-interactive', 'invisible', 'managed']
  - name: name
    value: "{{ name }}"
    description: |
      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.
  - name: offlabel
    value: {{ offlabel }}
    description: |
      Do not show any Cloudflare branding on the widget (ENT only).
  - name: region
    value: "{{ region }}"
    description: |
      Region where this widget can be used. This cannot be changed after creation.
    valid_values: ['world', 'china']
    default: world
  - name: page
    value: {{ page }}
  - name: per_page
    value: {{ per_page }}
  - name: order
    value: "{{ order }}"
  - name: direction
    value: "{{ direction }}"
  - name: filter
    value: "{{ filter }}"
    description: Filter widgets by field using case-insensitive substring matching. Format: `field:value` Supported fields: - `name` - Filter by widget name (e.g., `filter=name:login-form`) - `sitekey` - Filter by sitekey (e.g., `filter=sitekey:0x4AAA`) Returns 400 Bad Request if the field is unsupported or format is invalid. An empty filter value returns all results.
    description: Filter widgets by field using case-insensitive substring matching. Format: `field:value` Supported fields: - `name` - Filter by widget name (e.g., `filter=name:login-form`) - `sitekey` - Filter by sitekey (e.g., `filter=sitekey:0x4AAA`) Returns 400 Bad Request if the field is unsupported or format is invalid. An empty filter value returns all results.

REPLACE examples

update

Update the configuration of a widget.

REPLACE cloudflare.turnstile.widgets
SET 
bot_fight_mode = {{ bot_fight_mode }},
clearance_level = '{{ clearance_level }}',
domains = '{{ domains }}',
ephemeral_id = {{ ephemeral_id }},
mode = '{{ mode }}',
name = '{{ name }}',
offlabel = {{ offlabel }},
region = '{{ region }}'
WHERE 
account_id = '{{ account_id }}' --required
AND sitekey = '{{ sitekey }}' --required
AND name = '{{ name }}' --required
AND mode = '{{ mode }}' --required
AND domains = '{{ domains }}' --required
RETURNING
errors,
messages,
result,
success;

DELETE examples

delete

Destroy a Turnstile Widget.

DELETE FROM cloudflare.turnstile.widgets
WHERE account_id = '{{ account_id }}' --required
AND sitekey = '{{ sitekey }}' --required
;

Lifecycle Methods

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.

EXEC cloudflare.turnstile.widgets.rotate_secret 
@account_id='{{ account_id }}' --required, 
@sitekey='{{ sitekey }}' --required 
@@json=
'{
"invalidate_immediately": {{ invalidate_immediately }}
}'
;