INTEGRITY Cloudflare Docs

← Turnstile / turnstile / get-started / widget-management

Create and manage widgets using Cloudflare API

Use the Cloudflare API for programmatic widget management and automation.

Prerequisites

Before you begin, you must have:

Create a widget via the API

Required API token permissions

At least one of the following token permissions is required:
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:
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 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:
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:
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:
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"