--- title: Create a Turnstile Widget --- [Skip to content](#_top) [API Reference](https://developers.cloudflare.com/api/go) [Turnstile](https://developers.cloudflare.com/api/go/resources/turnstile) [Widgets](https://developers.cloudflare.com/api/go/resources/turnstile/subresources/widgets) Copy Markdown Open in **Claude**Open in **ChatGPT**Open in **Cursor** --- **Copy Markdown****View as Markdown** # Create a Turnstile Widget client.Turnstile.Widgets.New(ctx, params) (\*[Widget](), error) POST/accounts/{account\_id}/challenges/widgets Creates a Turnstile widget for an account. ##### Security
API Token The preferred authorization scheme for interacting with the Cloudflare API. Create a token. **Example:**Authorization: Bearer Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY
API Email + API Key The previous authorization scheme for interacting with the Cloudflare API, used in conjunction with a Global API key. **Example:**X-Auth-Email: user@example.com The previous authorization scheme for interacting with the Cloudflare API. When possible, use API tokens instead of Global API keys. **Example:**X-Auth-Key: 144c9defac04969c7bfad8efaa8ea194
##### Accepted Permissions (at least one required) `Turnstile Sites Write``Account Settings Write` ##### ParametersExpand Collapse
params WidgetNewParams AccountID param.Field\[string] Path param: Identifier maxLength32 Link to this property Domains param.Field\[\[]WidgetDomain] Body param maxLength10 Link to this property
Mode param.Field\[WidgetNewParamsMode] Body param: Widget Mode const WidgetNewParamsModeNonInteractive WidgetNewParamsMode = "non-interactive" Link to this property const WidgetNewParamsModeInvisible WidgetNewParamsMode = "invisible" Link to this property const WidgetNewParamsModeManaged WidgetNewParamsMode = "managed" Link to this property
Link to this property Name param.Field\[string] Body param: Human readable widget name. Not unique. Cloudflare suggests that you set this to a meaningful string to make it easier to identify your widget, and where it is used. maxLength254 minLength1 Link to this property
Direction param.Field\[WidgetNewParamsDirection]Optional Query param: Direction to order widgets. const WidgetNewParamsDirectionAsc WidgetNewParamsDirection = "asc" Link to this property const WidgetNewParamsDirectionDesc WidgetNewParamsDirection = "desc" Link to this property
Link to this property Filter param.Field\[string]Optional Query param: Filter widgets by field. The name field uses case-insensitive substring matching; sitekey uses exact matching. Format: field:value Supported fields: - name - Filter by widget name (e.g., filter=name:login-form) - sitekey - Filter by sitekey (e.g., filter=sitekey:0x4AAA) Returns 400 Bad Request if the field is unsupported or format is invalid. An empty filter value returns all results. Link to this property
Order param.Field\[WidgetNewParamsOrder]Optional Query param: Field to order widgets by. const WidgetNewParamsOrderID WidgetNewParamsOrder = "id" Link to this property const WidgetNewParamsOrderSitekey WidgetNewParamsOrder = "sitekey" Link to this property const WidgetNewParamsOrderName WidgetNewParamsOrder = "name" Link to this property const WidgetNewParamsOrderCreatedOn WidgetNewParamsOrder = "created\_on" Link to this property const WidgetNewParamsOrderModifiedOn WidgetNewParamsOrder = "modified\_on" Link to this property
Link to this property Page param.Field\[float64]Optional Query param: Page number of paginated results. minimum1 Link to this property PerPage param.Field\[float64]Optional Query param: Number of items per page. maximum1000 minimum5 Link to this property BotFightMode param.Field\[bool]Optional Body param: If bot\_fight\_mode is set to true, Cloudflare issues computationally expensive challenges in response to malicious bots (ENT only). Link to this property
ClearanceLevel param.Field\[WidgetNewParamsClearanceLevel]Optional Body param: If Turnstile is embedded on a Cloudflare site and the widget should grant challenge clearance, this setting can determine the clearance level to be set const WidgetNewParamsClearanceLevelNoClearance WidgetNewParamsClearanceLevel = "no\_clearance" Link to this property const WidgetNewParamsClearanceLevelJschallenge WidgetNewParamsClearanceLevel = "jschallenge" Link to this property const WidgetNewParamsClearanceLevelManaged WidgetNewParamsClearanceLevel = "managed" Link to this property const WidgetNewParamsClearanceLevelInteractive WidgetNewParamsClearanceLevel = "interactive" Link to this property
Link to this property EphemeralID param.Field\[bool]Optional Body param: Return the Ephemeral ID in /siteverify (ENT only). Link to this property Offlabel param.Field\[bool]Optional Body param: Do not show any Cloudflare branding on the widget (ENT only). Link to this property
Region param.Field\[WidgetNewParamsRegion]Optional Body param: Region where this widget can be used. This cannot be changed after creation. const WidgetNewParamsRegionWorld WidgetNewParamsRegion = "world" Link to this property const WidgetNewParamsRegionChina WidgetNewParamsRegion = "china" Link to this property
Link to this property
[Link to this property](<#(resource)%20turnstile.widgets%20%3E%20(method)%20create%20%3E%20(params)%20default>) ##### ReturnsExpand Collapse
type Widget struct{…} A Turnstile widget’s detailed configuration BotFightMode bool If bot\_fight\_mode is set to true, Cloudflare issues computationally expensive challenges in response to malicious bots (ENT only). Link to this property
ClearanceLevel WidgetClearanceLevel If Turnstile is embedded on a Cloudflare site and the widget should grant challenge clearance, this setting can determine the clearance level to be set One of the following: const WidgetClearanceLevelNoClearance WidgetClearanceLevel = "no\_clearance" Link to this property const WidgetClearanceLevelJschallenge WidgetClearanceLevel = "jschallenge" Link to this property const WidgetClearanceLevelManaged WidgetClearanceLevel = "managed" Link to this property const WidgetClearanceLevelInteractive WidgetClearanceLevel = "interactive" Link to this property
Link to this property CreatedOn Time When the widget was created. formatdate-time Link to this property Domains \[]WidgetDomain maxLength10 Link to this property EphemeralID bool Return the Ephemeral ID in /siteverify (ENT only). Link to this property
Mode WidgetMode Widget Mode One of the following: const WidgetModeNonInteractive WidgetMode = "non-interactive" Link to this property const WidgetModeInvisible WidgetMode = "invisible" Link to this property const WidgetModeManaged WidgetMode = "managed" Link to this property
Link to this property ModifiedOn Time When the widget was modified. formatdate-time Link to this property Name string Human readable widget name. Not unique. Cloudflare suggests that you set this to a meaningful string to make it easier to identify your widget, and where it is used. maxLength254 minLength1 Link to this property Offlabel bool Do not show any Cloudflare branding on the widget (ENT only). Link to this property
Region WidgetRegion Region where this widget can be used. This cannot be changed after creation. One of the following: const WidgetRegionWorld WidgetRegion = "world" Link to this property const WidgetRegionChina WidgetRegion = "china" Link to this property
Link to this property Secret string Secret key for this widget. Link to this property Sitekey string Unique identifier for a Turnstile widget. maxLength32 Link to this property
DeployedVia WidgetDeployedViaOptional Origin that created this widget, recorded at creation time and immutable afterward. Server-derived from the create request; not client-settable. Omitted from the response for widgets created before this field existed. One of the following: const WidgetDeployedViaWrangler WidgetDeployedVia = "wrangler" Link to this property const WidgetDeployedViaDashboard WidgetDeployedVia = "dashboard" Link to this property const WidgetDeployedViaSpin WidgetDeployedVia = "spin" Link to this property const WidgetDeployedViaAPI WidgetDeployedVia = "api" Link to this property const WidgetDeployedViaUnknown WidgetDeployedVia = "unknown" Link to this property
Link to this property
LastModifiedVia WidgetLastModifiedViaOptional Origin of the most recent mutation (create, update, delete, or secret rotation). Server-derived; not client-settable. Omitted for widgets last mutated before this field existed. One of the following: const WidgetLastModifiedViaWrangler WidgetLastModifiedVia = "wrangler" Link to this property const WidgetLastModifiedViaDashboard WidgetLastModifiedVia = "dashboard" Link to this property const WidgetLastModifiedViaSpin WidgetLastModifiedVia = "spin" Link to this property const WidgetLastModifiedViaAPI WidgetLastModifiedVia = "api" Link to this property const WidgetLastModifiedViaUnknown WidgetLastModifiedVia = "unknown" Link to this property
Link to this property
[Link to this property](<#(resource)%20turnstile.widgets%20%3E%20(model)%20widget%20%3E%20(schema)>) ### Create a Turnstile Widget Go HTTPTypeScriptPythonGoTerraform ``` package main import ( "context" "fmt" "github.com/cloudflare/cloudflare-go" "github.com/cloudflare/cloudflare-go/option" "github.com/cloudflare/cloudflare-go/turnstile" ) func main() { client := cloudflare.NewClient( option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"), ) widget, err := client.Turnstile.Widgets.New(context.TODO(), turnstile.WidgetNewParams{ AccountID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"), Domains: cloudflare.F([]turnstile.WidgetDomainParam{"203.0.113.1", "cloudflare.com", "blog.example.com"}), Mode: cloudflare.F(turnstile.WidgetNewParamsModeInvisible), Name: cloudflare.F("blog.cloudflare.com login form"), }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", widget.EphemeralID) } ``` 200 example ``` { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "success": true, "result": { "bot_fight_mode": false, "clearance_level": "interactive", "created_on": "2014-01-01T05:20:00.123123Z", "domains": [ "203.0.113.1", "cloudflare.com", "blog.example.com" ], "ephemeral_id": false, "mode": "invisible", "modified_on": "2014-01-01T05:20:00.123123Z", "name": "blog.cloudflare.com login form", "offlabel": false, "region": "world", "secret": "0x4AAF00AAAABn0R22HWm098HVBjhdsYUc", "sitekey": "0x4AAF00AAAABn0R22HWm-YUc", "deployed_via": "wrangler", "last_modified_via": "dashboard" }, "result_info": { "count": 1, "page": 1, "per_page": 20, "total_count": 2000 } } ``` ##### Returns Examples 200 example ``` { "errors": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "messages": [ { "code": 1000, "message": "message", "documentation_url": "documentation_url", "source": { "pointer": "pointer" } } ], "success": true, "result": { "bot_fight_mode": false, "clearance_level": "interactive", "created_on": "2014-01-01T05:20:00.123123Z", "domains": [ "203.0.113.1", "cloudflare.com", "blog.example.com" ], "ephemeral_id": false, "mode": "invisible", "modified_on": "2014-01-01T05:20:00.123123Z", "name": "blog.cloudflare.com login form", "offlabel": false, "region": "world", "secret": "0x4AAF00AAAABn0R22HWm098HVBjhdsYUc", "sitekey": "0x4AAF00AAAABn0R22HWm-YUc", "deployed_via": "wrangler", "last_modified_via": "dashboard" }, "result_info": { "count": 1, "page": 1, "per_page": 20, "total_count": 2000 } } ```