Cloudflare API | Turnstile › Widgets › Create A Turnstile Widget

API Reference

Account & User Management

Resource Sharing

AI

Certificate Management

Certificate Authorities

Client Certificates

Custom Certificates

Custom Hostnames

Keyless Certificates

MTLS Certificates

Origin CA Certificates

Origin Post Quantum Encryption

Origin TLS Client Auth

Cloudflare One

DNS

Account Custom Nameservers

Domain/Zone Management

IP Addresses

Media

Networking

Magic Cloud Networking

Magic Network Monitoring

Network Interconnects

Observability

Security Center

Radar

Routing & Performance

Rules

Cloud Connector

Managed Transforms

URL Normalization

Security

Schema Validation

Content Scanning

Leaked Credential Checks

Create a Turnstile Widget

Delete a Turnstile Widget

Turnstile Widget Details

List Turnstile Widgets

Rotate Secret for a Turnstile Widget

Update a Turnstile Widget

Storage & Databases

Threat Intelligence

Brand Protection

Workers & Pages

Browser Rendering

Durable Objects

Workers For Platforms

Shared

Turnstile

turnstile

Widgets

turnstile.widgets

Methods

Create A Turnstile Widget -> Envelope<

>

post/accounts/{account_id}/challenges/widgets

Lists challenge widgets.

Security

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

Example: Authorization: Bearer Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY

Accepted Permissions (at least one required)

Turnstile Sites Write Account Settings Write

path Parameters

account_id: string

(maxLength: 32)

Identifier

query Parameters

direction:

Optional

Direction to order widgets.

"asc"

"desc"

order:

Optional

Field to order widgets by.

"id"

"sitekey"

"name"

"created_on"

"modified_on"

page: number

Optional

(minimum: 1, default: 1)

Page number of paginated results.

per_page: number

Optional

(maximum: 1000, minimum: 5, default: 25)

Number of items per page.

Response fields

errors: Array<

>

messages: Array<

>

success: boolean

Whether the API call was successful

result:

Optional

A Turnstile widget's detailed configuration

result_info: { count, page, per_page, 1 more... }

Optional

Request example

curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/challenges/widgets \
    -H 'Content-Type: application/json' \
    -H "X-Auth-Email: $CLOUDFLARE_EMAIL" \
    -H "X-Auth-Key: $CLOUDFLARE_API_KEY" \
    -d '{
      "domains": [
        "203.0.113.1",
        "cloudflare.com",
        "blog.example.com"
      ],
      "mode": "invisible",
      "name": "blog.cloudflare.com login form",
      "clearance_level": "interactive"
    }'

200Example

{
  "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",
    "domains": [
      "203.0.113.1",
      "cloudflare.com",
      "blog.example.com"
    ],
    "ephemeral_id": false,
    "mode": "invisible",
    "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
  }
}

Delete A Turnstile Widget -> Envelope<

>

delete/accounts/{account_id}/challenges/widgets/{sitekey}

Destroy a Turnstile Widget.

Turnstile Widget Details -> Envelope<

>

get/accounts/{account_id}/challenges/widgets/{sitekey}

Show a single challenge widget configuration.

List Turnstile Widgets -> V4PagePaginationArray<{ bot_fight_mode, clearance_level, created_on, 8 more... }>

get/accounts/{account_id}/challenges/widgets

Lists all turnstile widgets of an account.

Rotate Secret For A Turnstile Widget -> Envelope<

>

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.

Update A Turnstile Widget -> Envelope<

>

put/accounts/{account_id}/challenges/widgets/{sitekey}

Update the configuration of a widget.

Domain types

Widget = { bot_fight_mode, clearance_level, created_on, 9 more... }

A Turnstile widget's detailed configuration

WidgetDomain = string

Hosts as a hostname or IPv4/IPv6 address represented by strings. The widget will only work on these domains, and their subdomains.