# Turnstile # Widgets ## List Turnstile Widgets `client.turnstile.widgets.list(WidgetListParamsparams, RequestOptionsoptions?): V4PagePaginationArray` **get** `/accounts/{account_id}/challenges/widgets` Lists all turnstile widgets of an account. ### Parameters - `params: WidgetListParams` - `account_id: string` Path param: Identifier - `direction?: "asc" | "desc"` Query param: Direction to order widgets. - `"asc"` - `"desc"` - `filter?: string` Query param: 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?: "id" | "sitekey" | "name" | 2 more` Query param: Field to order widgets by. - `"id"` - `"sitekey"` - `"name"` - `"created_on"` - `"modified_on"` - `page?: number` Query param: Page number of paginated results. - `per_page?: number` Query param: Number of items per page. ### Returns - `WidgetListResponse` A Turnstile Widgets configuration as it appears in listings - `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: "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 - `"no_clearance"` - `"jschallenge"` - `"managed"` - `"interactive"` - `created_on: string` When the widget was created. - `domains: Array` - `ephemeral_id: boolean` Return the Ephemeral ID in /siteverify (ENT only). - `mode: "non-interactive" | "invisible" | "managed"` Widget Mode - `"non-interactive"` - `"invisible"` - `"managed"` - `modified_on: string` When the widget was modified. - `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. - `offlabel: boolean` Do not show any Cloudflare branding on the widget (ENT only). - `region: "world" | "china"` Region where this widget can be used. This cannot be changed after creation. - `"world"` - `"china"` - `sitekey: string` Widget item identifier tag. ### Example ```node import Cloudflare from 'cloudflare'; const client = new Cloudflare({ apiToken: process.env['CLOUDFLARE_API_TOKEN'], // This is the default and can be omitted }); // Automatically fetches more pages as needed. for await (const widgetListResponse of client.turnstile.widgets.list({ account_id: '023e105f4ecef8ad9ca31a8372d0c353', })) { console.log(widgetListResponse.ephemeral_id); } ``` #### Response ```json { "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", "sitekey": "0x4AAF00AAAABn0R22HWm-YUc" } ], "result_info": { "count": 1, "page": 1, "per_page": 20, "total_count": 2000 } } ``` ## Turnstile Widget Details `client.turnstile.widgets.get(stringsitekey, WidgetGetParamsparams, RequestOptionsoptions?): Widget` **get** `/accounts/{account_id}/challenges/widgets/{sitekey}` Show a single challenge widget configuration. ### Parameters - `sitekey: string` Widget item identifier tag. - `params: WidgetGetParams` - `account_id: string` Identifier ### Returns - `Widget` A Turnstile widget's detailed configuration - `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: "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 - `"no_clearance"` - `"jschallenge"` - `"managed"` - `"interactive"` - `created_on: string` When the widget was created. - `domains: Array` - `ephemeral_id: boolean` Return the Ephemeral ID in /siteverify (ENT only). - `mode: "non-interactive" | "invisible" | "managed"` Widget Mode - `"non-interactive"` - `"invisible"` - `"managed"` - `modified_on: string` When the widget was modified. - `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. - `offlabel: boolean` Do not show any Cloudflare branding on the widget (ENT only). - `region: "world" | "china"` Region where this widget can be used. This cannot be changed after creation. - `"world"` - `"china"` - `secret: string` Secret key for this widget. - `sitekey: string` Widget item identifier tag. ### Example ```node import Cloudflare from 'cloudflare'; const client = new Cloudflare({ apiToken: process.env['CLOUDFLARE_API_TOKEN'], // This is the default and can be omitted }); const widget = await client.turnstile.widgets.get('0x4AAF00AAAABn0R22HWm-YUc', { account_id: '023e105f4ecef8ad9ca31a8372d0c353', }); console.log(widget.ephemeral_id); ``` #### Response ```json { "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" } } ``` ## Create a Turnstile Widget `client.turnstile.widgets.create(WidgetCreateParamsparams, RequestOptionsoptions?): Widget` **post** `/accounts/{account_id}/challenges/widgets` Lists challenge widgets. ### Parameters - `params: WidgetCreateParams` - `account_id: string` Path param: Identifier - `domains: Array` Body param - `mode: "non-interactive" | "invisible" | "managed"` Body param: Widget Mode - `"non-interactive"` - `"invisible"` - `"managed"` - `name: string` Body param: 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. - `direction?: "asc" | "desc"` Query param: Direction to order widgets. - `"asc"` - `"desc"` - `filter?: string` Query param: 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?: "id" | "sitekey" | "name" | 2 more` Query param: Field to order widgets by. - `"id"` - `"sitekey"` - `"name"` - `"created_on"` - `"modified_on"` - `page?: number` Query param: Page number of paginated results. - `per_page?: number` Query param: Number of items per page. - `bot_fight_mode?: boolean` Body param: If bot_fight_mode is set to `true`, Cloudflare issues computationally expensive challenges in response to malicious bots (ENT only). - `clearance_level?: "no_clearance" | "jschallenge" | "managed" | "interactive"` Body param: 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"` - `ephemeral_id?: boolean` Body param: Return the Ephemeral ID in /siteverify (ENT only). - `offlabel?: boolean` Body param: Do not show any Cloudflare branding on the widget (ENT only). - `region?: "world" | "china"` Body param: Region where this widget can be used. This cannot be changed after creation. - `"world"` - `"china"` ### Returns - `Widget` A Turnstile widget's detailed configuration - `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: "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 - `"no_clearance"` - `"jschallenge"` - `"managed"` - `"interactive"` - `created_on: string` When the widget was created. - `domains: Array` - `ephemeral_id: boolean` Return the Ephemeral ID in /siteverify (ENT only). - `mode: "non-interactive" | "invisible" | "managed"` Widget Mode - `"non-interactive"` - `"invisible"` - `"managed"` - `modified_on: string` When the widget was modified. - `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. - `offlabel: boolean` Do not show any Cloudflare branding on the widget (ENT only). - `region: "world" | "china"` Region where this widget can be used. This cannot be changed after creation. - `"world"` - `"china"` - `secret: string` Secret key for this widget. - `sitekey: string` Widget item identifier tag. ### Example ```node import Cloudflare from 'cloudflare'; const client = new Cloudflare({ apiToken: process.env['CLOUDFLARE_API_TOKEN'], // This is the default and can be omitted }); const widget = await client.turnstile.widgets.create({ account_id: '023e105f4ecef8ad9ca31a8372d0c353', domains: ['203.0.113.1', 'cloudflare.com', 'blog.example.com'], mode: 'invisible', name: 'blog.cloudflare.com login form', }); console.log(widget.ephemeral_id); ``` #### Response ```json { "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" }, "result_info": { "count": 1, "page": 1, "per_page": 20, "total_count": 2000 } } ``` ## Update a Turnstile Widget `client.turnstile.widgets.update(stringsitekey, WidgetUpdateParamsparams, RequestOptionsoptions?): Widget` **put** `/accounts/{account_id}/challenges/widgets/{sitekey}` Update the configuration of a widget. ### Parameters - `sitekey: string` Widget item identifier tag. - `params: WidgetUpdateParams` - `account_id: string` Path param: Identifier - `domains: Array` Body param - `mode: "non-interactive" | "invisible" | "managed"` Body param: Widget Mode - `"non-interactive"` - `"invisible"` - `"managed"` - `name: string` Body param: 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. - `bot_fight_mode?: boolean` Body param: If bot_fight_mode is set to `true`, Cloudflare issues computationally expensive challenges in response to malicious bots (ENT only). - `clearance_level?: "no_clearance" | "jschallenge" | "managed" | "interactive"` Body param: 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"` - `ephemeral_id?: boolean` Body param: Return the Ephemeral ID in /siteverify (ENT only). - `offlabel?: boolean` Body param: Do not show any Cloudflare branding on the widget (ENT only). - `region?: "world" | "china"` Body param: Region where this widget can be used. This cannot be changed after creation. - `"world"` - `"china"` ### Returns - `Widget` A Turnstile widget's detailed configuration - `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: "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 - `"no_clearance"` - `"jschallenge"` - `"managed"` - `"interactive"` - `created_on: string` When the widget was created. - `domains: Array` - `ephemeral_id: boolean` Return the Ephemeral ID in /siteverify (ENT only). - `mode: "non-interactive" | "invisible" | "managed"` Widget Mode - `"non-interactive"` - `"invisible"` - `"managed"` - `modified_on: string` When the widget was modified. - `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. - `offlabel: boolean` Do not show any Cloudflare branding on the widget (ENT only). - `region: "world" | "china"` Region where this widget can be used. This cannot be changed after creation. - `"world"` - `"china"` - `secret: string` Secret key for this widget. - `sitekey: string` Widget item identifier tag. ### Example ```node import Cloudflare from 'cloudflare'; const client = new Cloudflare({ apiToken: process.env['CLOUDFLARE_API_TOKEN'], // This is the default and can be omitted }); const widget = await client.turnstile.widgets.update('0x4AAF00AAAABn0R22HWm-YUc', { account_id: '023e105f4ecef8ad9ca31a8372d0c353', domains: ['203.0.113.1', 'cloudflare.com', 'blog.example.com'], mode: 'invisible', name: 'blog.cloudflare.com login form', }); console.log(widget.ephemeral_id); ``` #### Response ```json { "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" } } ``` ## Delete a Turnstile Widget `client.turnstile.widgets.delete(stringsitekey, WidgetDeleteParamsparams, RequestOptionsoptions?): Widget` **delete** `/accounts/{account_id}/challenges/widgets/{sitekey}` Destroy a Turnstile Widget. ### Parameters - `sitekey: string` Widget item identifier tag. - `params: WidgetDeleteParams` - `account_id: string` Identifier ### Returns - `Widget` A Turnstile widget's detailed configuration - `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: "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 - `"no_clearance"` - `"jschallenge"` - `"managed"` - `"interactive"` - `created_on: string` When the widget was created. - `domains: Array` - `ephemeral_id: boolean` Return the Ephemeral ID in /siteverify (ENT only). - `mode: "non-interactive" | "invisible" | "managed"` Widget Mode - `"non-interactive"` - `"invisible"` - `"managed"` - `modified_on: string` When the widget was modified. - `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. - `offlabel: boolean` Do not show any Cloudflare branding on the widget (ENT only). - `region: "world" | "china"` Region where this widget can be used. This cannot be changed after creation. - `"world"` - `"china"` - `secret: string` Secret key for this widget. - `sitekey: string` Widget item identifier tag. ### Example ```node import Cloudflare from 'cloudflare'; const client = new Cloudflare({ apiToken: process.env['CLOUDFLARE_API_TOKEN'], // This is the default and can be omitted }); const widget = await client.turnstile.widgets.delete('0x4AAF00AAAABn0R22HWm-YUc', { account_id: '023e105f4ecef8ad9ca31a8372d0c353', }); console.log(widget.ephemeral_id); ``` #### Response ```json { "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" } } ``` ## Rotate Secret for a Turnstile Widget `client.turnstile.widgets.rotateSecret(stringsitekey, WidgetRotateSecretParamsparams, RequestOptionsoptions?): 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. ### Parameters - `sitekey: string` Widget item identifier tag. - `params: WidgetRotateSecretParams` - `account_id: string` Path param: Identifier - `invalidate_immediately?: boolean` Body param: 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. ### Returns - `Widget` A Turnstile widget's detailed configuration - `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: "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 - `"no_clearance"` - `"jschallenge"` - `"managed"` - `"interactive"` - `created_on: string` When the widget was created. - `domains: Array` - `ephemeral_id: boolean` Return the Ephemeral ID in /siteverify (ENT only). - `mode: "non-interactive" | "invisible" | "managed"` Widget Mode - `"non-interactive"` - `"invisible"` - `"managed"` - `modified_on: string` When the widget was modified. - `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. - `offlabel: boolean` Do not show any Cloudflare branding on the widget (ENT only). - `region: "world" | "china"` Region where this widget can be used. This cannot be changed after creation. - `"world"` - `"china"` - `secret: string` Secret key for this widget. - `sitekey: string` Widget item identifier tag. ### Example ```node import Cloudflare from 'cloudflare'; const client = new Cloudflare({ apiToken: process.env['CLOUDFLARE_API_TOKEN'], // This is the default and can be omitted }); const widget = await client.turnstile.widgets.rotateSecret('0x4AAF00AAAABn0R22HWm-YUc', { account_id: '023e105f4ecef8ad9ca31a8372d0c353', }); console.log(widget.ephemeral_id); ``` #### Response ```json { "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" } } ``` ## Domain Types ### Widget - `Widget` A Turnstile widget's detailed configuration - `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: "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 - `"no_clearance"` - `"jschallenge"` - `"managed"` - `"interactive"` - `created_on: string` When the widget was created. - `domains: Array` - `ephemeral_id: boolean` Return the Ephemeral ID in /siteverify (ENT only). - `mode: "non-interactive" | "invisible" | "managed"` Widget Mode - `"non-interactive"` - `"invisible"` - `"managed"` - `modified_on: string` When the widget was modified. - `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. - `offlabel: boolean` Do not show any Cloudflare branding on the widget (ENT only). - `region: "world" | "china"` Region where this widget can be used. This cannot be changed after creation. - `"world"` - `"china"` - `secret: string` Secret key for this widget. - `sitekey: string` Widget item identifier tag. ### Widget Domain - `WidgetDomain = string` Hosts as a hostname or IPv4/IPv6 address represented by strings. The widget will only work on these domains, and their subdomains. ### Widget List Response - `WidgetListResponse` A Turnstile Widgets configuration as it appears in listings - `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: "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 - `"no_clearance"` - `"jschallenge"` - `"managed"` - `"interactive"` - `created_on: string` When the widget was created. - `domains: Array` - `ephemeral_id: boolean` Return the Ephemeral ID in /siteverify (ENT only). - `mode: "non-interactive" | "invisible" | "managed"` Widget Mode - `"non-interactive"` - `"invisible"` - `"managed"` - `modified_on: string` When the widget was modified. - `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. - `offlabel: boolean` Do not show any Cloudflare branding on the widget (ENT only). - `region: "world" | "china"` Region where this widget can be used. This cannot be changed after creation. - `"world"` - `"china"` - `sitekey: string` Widget item identifier tag.