---
description: Create and manage Turnstile widgets using the Cloudflare API.
title: Create and manage widgets using Cloudflare API
image: https://developers.cloudflare.com/og-docs.png
---
[Skip to content](#main-content)
> Documentation Index
> Fetch the complete documentation index at: https://developers.cloudflare.com/turnstile/llms.txt
> Use this file to discover all available pages before exploring further.
# Create and manage widgets using Cloudflare API
Last updated Aug 31, 2026|Copy as Markdown| [View as Markdown](https://fec4cfc0.previews.developers.cloudflare.com/turnstile/get-started/widget-management/api/index.md)| [Agent setup](https://fec4cfc0.previews.developers.cloudflare.com/agent-setup/)
Use the [Cloudflare API](https://fec4cfc0.previews.developers.cloudflare.com/api/resources/turnstile/) 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*
```bash
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*
```bash
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*
```bash
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*
```bash
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*
```bash
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*
```bash
curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/challenges/widgets/$SITEKEY" \
--request DELETE \
--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"
```
Was this helpful?
YesNo
## On this page
[Docs](https://fec4cfc0.previews.developers.cloudflare.com/)
```json
{"@context":"https://schema.org","@type":"TechArticle","@id":"https://developers.cloudflare.com/turnstile/get-started/widget-management/api/#page","headline":"Create and manage widgets using Cloudflare API ยท Cloudflare Turnstile docs","description":"Create and manage Turnstile widgets using the Cloudflare API.","url":"https://developers.cloudflare.com/turnstile/get-started/widget-management/api/","inLanguage":"en","image":"https://developers.cloudflare.com/og-docs.png","dateModified":"2026-08-31","publisher":{"@type":"Organization","name":"Cloudflare","description":"One platform for your apps, agents, and workforce. Build, secure, and scale without managing infrastructure","url":"https://www.cloudflare.com/","sameAs":["https://github.com/cloudflare","https://www.linkedin.com/company/cloudflare","https://x.com/cloudflare"],"logo":{"@type":"ImageObject","url":"https://developers.cloudflare.com/logo.svg"},"address":{"@type":"PostalAddress","streetAddress":"101 Townsend St","addressLocality":"San Francisco","addressRegion":"CA","postalCode":"94107","addressCountry":"US"},"contactPoint":[{"@type":"ContactPoint","contactType":"Customer Support","url":"https://support.cloudflare.com/","availableLanguage":["English"]},{"@type":"ContactPoint","contactType":"Sales","url":"https://www.cloudflare.com/contact/","availableLanguage":["English"]}]},"isPartOf":{"@type":"WebSite","@id":"https://developers.cloudflare.com/#website","name":"Cloudflare Docs","url":"https://developers.cloudflare.com/"},"keywords":["REST API"]}
```