Create and manage widgets using Cloudflare API

Last updated May 5, 2026 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

<details>

<summary>

Required API token permissions

</summary>

At least one of the following <a href="https://developers.cloudflare.com/fundamentals/api/reference/permissions/">token permissions</a> is required:

• <code>Turnstile Sites Write</code>
• <code>Account Settings Write</code>

</details>

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

<details>

<summary>

Required API token permissions

</summary>

At least one of the following <a href="https://developers.cloudflare.com/fundamentals/api/reference/permissions/">token permissions</a> is required:

• <code>Turnstile Sites Write</code>
• <code>Turnstile Sites Read</code>
• <code>Account Settings Write</code>
• <code>Account Settings Read</code>

</details>

List Turnstile Widgetsbash

curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/challenges/widgets" \
    --request GET \
    --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

<details>

<summary>

Required API token permissions

</summary>

At least one of the following <a href="https://developers.cloudflare.com/fundamentals/api/reference/permissions/">token permissions</a> is required:

• <code>Turnstile Sites Write</code>
• <code>Turnstile Sites Read</code>
• <code>Account Settings Write</code>
• <code>Account Settings Read</code>

</details>

Turnstile Widget Detailsbash

curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/challenges/widgets/$SITEKEY" \
    --request GET \
    --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

<details>

<summary>

Required API token permissions

</summary>

At least one of the following <a href="https://developers.cloudflare.com/fundamentals/api/reference/permissions/">token permissions</a> is required:

• <code>Turnstile Sites Write</code>
• <code>Account Settings Write</code>

</details>

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"
    }'

<details>

<summary>

Required API token permissions

</summary>

At least one of the following <a href="https://developers.cloudflare.com/fundamentals/api/reference/permissions/">token permissions</a> is required:

• <code>Turnstile Sites Write</code>
• <code>Account Settings Write</code>

</details>

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
    }'

<details>

<summary>

Required API token permissions

</summary>

At least one of the following <a href="https://developers.cloudflare.com/fundamentals/api/reference/permissions/">token permissions</a> is required:

• <code>Turnstile Sites Write</code>
• <code>Account Settings Write</code>

</details>

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?

YesNo

On this page

Docs

{"@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","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/turnstile/get-started/widget-management/api/og.png?v=3ee3163dce753625","dateModified":"2026-05-05","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"]}

description: Create and manage Turnstile widgets in the Cloudflare dashboard. title: Create and manage widgets using the Cloudflare dashboard image: https://developers.cloudflare.com/turnstile/get-started/widget-management/dashboard/og.png?v=68fe631d03f85103

Skip to 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.