Skip to content
Cloudflare Docs

API

Use the Cloudflare API for programmatic widget management and automation.

Prerequisites

Before you begin, you must have:

  • A Cloudflare API token with Account:Turnstile:Edit permissions
  • An account ID found in your Cloudflare dashboard

Create a widget via the API

Required API token permissions

 At least one of the following token permissions is required:
  • Turnstile Sites Write
  • Account Settings Write
Create a Turnstile Widget
curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/challenges/widgets" \
  --request POST \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --json '{
    "domains": [
        "example.com"
    ],
    "mode": "managed",
    "name": "My Example Turnstile Widget"
  }'

Manage widgets via the API

Required API token permissions

 At least one of the following token permissions is required:
  • Turnstile Sites Write
  • Turnstile Sites Read
  • Account Settings Write
  • Account Settings Read
List Turnstile Widgets
curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/challenges/widgets" \
  --request GET \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

Required API token permissions

 At least one of the following token permissions is required:
  • Turnstile Sites Write
  • Turnstile Sites Read
  • Account Settings Write
  • Account Settings Read
Turnstile Widget Details
curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/challenges/widgets/$SITEKEY" \
  --request GET \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

Required API token permissions

 At least one of the following token permissions is required:
  • Turnstile Sites Write
  • Account Settings Write
Update a Turnstile Widget
curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/challenges/widgets/$SITEKEY" \
  --request PUT \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --json '{
    "domains": [
        "203.0.113.1",
        "cloudflare.com",
        "blog.example.com"
    ],
    "mode": "invisible",
    "name": "blog.cloudflare.com login form",
    "clearance_level": "interactive"
  }'

Required API token permissions

 At least one of the following token permissions is required:
  • Turnstile Sites Write
  • Account Settings Write
Rotate Secret for a Turnstile Widget
curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/challenges/widgets/$SITEKEY/rotate_secret" \
  --request POST \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --json '{
    "invalidate_immediately": false
  }'

Required API token permissions

 At least one of the following token permissions is required:
  • Turnstile Sites Write
  • Account Settings Write
Delete a Turnstile Widget
curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/challenges/widgets/$SITEKEY" \
  --request DELETE \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"