Skip to content

Create and manage widgets using Cloudflare API

Last updated View as Markdown Agent setup

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 Widgetbash
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 Widgetsbash
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 Detailsbash
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 Widgetbash
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 Widgetbash
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 Widgetbash
curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/challenges/widgets/$SITEKEY" \
	--request DELETE \
	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

Was this helpful?