# Turnstile # Widgets ## List Turnstile Widgets `client.Turnstile.Widgets.List(ctx, params) (*V4PagePaginationArray[WidgetListResponse], error)` **get** `/accounts/{account_id}/challenges/widgets` Lists all turnstile widgets of an account. ### Parameters - `params WidgetListParams` - `AccountID param.Field[string]` Path param: Identifier - `Direction param.Field[WidgetListParamsDirection]` Query param: Direction to order widgets. - `const WidgetListParamsDirectionAsc WidgetListParamsDirection = "asc"` - `const WidgetListParamsDirectionDesc WidgetListParamsDirection = "desc"` - `Filter param.Field[string]` Query param: Filter widgets by field using case-insensitive substring 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. - `Order param.Field[WidgetListParamsOrder]` Query param: Field to order widgets by. - `const WidgetListParamsOrderID WidgetListParamsOrder = "id"` - `const WidgetListParamsOrderSitekey WidgetListParamsOrder = "sitekey"` - `const WidgetListParamsOrderName WidgetListParamsOrder = "name"` - `const WidgetListParamsOrderCreatedOn WidgetListParamsOrder = "created_on"` - `const WidgetListParamsOrderModifiedOn WidgetListParamsOrder = "modified_on"` - `Page param.Field[float64]` Query param: Page number of paginated results. - `PerPage param.Field[float64]` Query param: Number of items per page. ### Returns - `type WidgetListResponse struct{…}` A Turnstile Widgets configuration as it appears in listings - `BotFightMode bool` If bot_fight_mode is set to `true`, Cloudflare issues computationally expensive challenges in response to malicious bots (ENT only). - `ClearanceLevel WidgetListResponseClearanceLevel` 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 WidgetListResponseClearanceLevelNoClearance WidgetListResponseClearanceLevel = "no_clearance"` - `const WidgetListResponseClearanceLevelJschallenge WidgetListResponseClearanceLevel = "jschallenge"` - `const WidgetListResponseClearanceLevelManaged WidgetListResponseClearanceLevel = "managed"` - `const WidgetListResponseClearanceLevelInteractive WidgetListResponseClearanceLevel = "interactive"` - `CreatedOn Time` When the widget was created. - `Domains []WidgetDomain` - `EphemeralID bool` Return the Ephemeral ID in /siteverify (ENT only). - `Mode WidgetListResponseMode` Widget Mode - `const WidgetListResponseModeNonInteractive WidgetListResponseMode = "non-interactive"` - `const WidgetListResponseModeInvisible WidgetListResponseMode = "invisible"` - `const WidgetListResponseModeManaged WidgetListResponseMode = "managed"` - `ModifiedOn Time` When the widget was modified. - `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. - `Offlabel bool` Do not show any Cloudflare branding on the widget (ENT only). - `Region WidgetListResponseRegion` Region where this widget can be used. This cannot be changed after creation. - `const WidgetListResponseRegionWorld WidgetListResponseRegion = "world"` - `const WidgetListResponseRegionChina WidgetListResponseRegion = "china"` - `Sitekey string` Widget item identifier tag. ### Example ```go 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"), ) page, err := client.Turnstile.Widgets.List(context.TODO(), turnstile.WidgetListParams{ AccountID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"), }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", page) } ``` #### Response ```json { "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", "sitekey": "0x4AAF00AAAABn0R22HWm-YUc" } ], "result_info": { "count": 1, "page": 1, "per_page": 20, "total_count": 2000 } } ``` ## Turnstile Widget Details `client.Turnstile.Widgets.Get(ctx, sitekey, query) (*Widget, error)` **get** `/accounts/{account_id}/challenges/widgets/{sitekey}` Show a single challenge widget configuration. ### Parameters - `sitekey string` Widget item identifier tag. - `query WidgetGetParams` - `AccountID param.Field[string]` Identifier ### Returns - `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). - `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 - `const WidgetClearanceLevelNoClearance WidgetClearanceLevel = "no_clearance"` - `const WidgetClearanceLevelJschallenge WidgetClearanceLevel = "jschallenge"` - `const WidgetClearanceLevelManaged WidgetClearanceLevel = "managed"` - `const WidgetClearanceLevelInteractive WidgetClearanceLevel = "interactive"` - `CreatedOn Time` When the widget was created. - `Domains []WidgetDomain` - `EphemeralID bool` Return the Ephemeral ID in /siteverify (ENT only). - `Mode WidgetMode` Widget Mode - `const WidgetModeNonInteractive WidgetMode = "non-interactive"` - `const WidgetModeInvisible WidgetMode = "invisible"` - `const WidgetModeManaged WidgetMode = "managed"` - `ModifiedOn Time` When the widget was modified. - `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. - `Offlabel bool` Do not show any Cloudflare branding on the widget (ENT only). - `Region WidgetRegion` Region where this widget can be used. This cannot be changed after creation. - `const WidgetRegionWorld WidgetRegion = "world"` - `const WidgetRegionChina WidgetRegion = "china"` - `Secret string` Secret key for this widget. - `Sitekey string` Widget item identifier tag. ### Example ```go 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.Get( context.TODO(), "0x4AAF00AAAABn0R22HWm-YUc", turnstile.WidgetGetParams{ AccountID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"), }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", widget.EphemeralID) } ``` #### Response ```json { "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" } } ``` ## Create a Turnstile Widget `client.Turnstile.Widgets.New(ctx, params) (*Widget, error)` **post** `/accounts/{account_id}/challenges/widgets` Lists challenge widgets. ### Parameters - `params WidgetNewParams` - `AccountID param.Field[string]` Path param: Identifier - `Domains param.Field[[]WidgetDomain]` Body param - `Mode param.Field[WidgetNewParamsMode]` Body param: Widget Mode - `const WidgetNewParamsModeNonInteractive WidgetNewParamsMode = "non-interactive"` - `const WidgetNewParamsModeInvisible WidgetNewParamsMode = "invisible"` - `const WidgetNewParamsModeManaged WidgetNewParamsMode = "managed"` - `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. - `Direction param.Field[WidgetNewParamsDirection]` Query param: Direction to order widgets. - `const WidgetNewParamsDirectionAsc WidgetNewParamsDirection = "asc"` - `const WidgetNewParamsDirectionDesc WidgetNewParamsDirection = "desc"` - `Filter param.Field[string]` Query param: Filter widgets by field using case-insensitive substring 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. - `Order param.Field[WidgetNewParamsOrder]` Query param: Field to order widgets by. - `const WidgetNewParamsOrderID WidgetNewParamsOrder = "id"` - `const WidgetNewParamsOrderSitekey WidgetNewParamsOrder = "sitekey"` - `const WidgetNewParamsOrderName WidgetNewParamsOrder = "name"` - `const WidgetNewParamsOrderCreatedOn WidgetNewParamsOrder = "created_on"` - `const WidgetNewParamsOrderModifiedOn WidgetNewParamsOrder = "modified_on"` - `Page param.Field[float64]` Query param: Page number of paginated results. - `PerPage param.Field[float64]` Query param: Number of items per page. - `BotFightMode param.Field[bool]` Body param: If bot_fight_mode is set to `true`, Cloudflare issues computationally expensive challenges in response to malicious bots (ENT only). - `ClearanceLevel param.Field[WidgetNewParamsClearanceLevel]` 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"` - `const WidgetNewParamsClearanceLevelJschallenge WidgetNewParamsClearanceLevel = "jschallenge"` - `const WidgetNewParamsClearanceLevelManaged WidgetNewParamsClearanceLevel = "managed"` - `const WidgetNewParamsClearanceLevelInteractive WidgetNewParamsClearanceLevel = "interactive"` - `EphemeralID param.Field[bool]` Body param: Return the Ephemeral ID in /siteverify (ENT only). - `Offlabel param.Field[bool]` Body param: Do not show any Cloudflare branding on the widget (ENT only). - `Region param.Field[WidgetNewParamsRegion]` Body param: Region where this widget can be used. This cannot be changed after creation. - `const WidgetNewParamsRegionWorld WidgetNewParamsRegion = "world"` - `const WidgetNewParamsRegionChina WidgetNewParamsRegion = "china"` ### Returns - `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). - `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 - `const WidgetClearanceLevelNoClearance WidgetClearanceLevel = "no_clearance"` - `const WidgetClearanceLevelJschallenge WidgetClearanceLevel = "jschallenge"` - `const WidgetClearanceLevelManaged WidgetClearanceLevel = "managed"` - `const WidgetClearanceLevelInteractive WidgetClearanceLevel = "interactive"` - `CreatedOn Time` When the widget was created. - `Domains []WidgetDomain` - `EphemeralID bool` Return the Ephemeral ID in /siteverify (ENT only). - `Mode WidgetMode` Widget Mode - `const WidgetModeNonInteractive WidgetMode = "non-interactive"` - `const WidgetModeInvisible WidgetMode = "invisible"` - `const WidgetModeManaged WidgetMode = "managed"` - `ModifiedOn Time` When the widget was modified. - `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. - `Offlabel bool` Do not show any Cloudflare branding on the widget (ENT only). - `Region WidgetRegion` Region where this widget can be used. This cannot be changed after creation. - `const WidgetRegionWorld WidgetRegion = "world"` - `const WidgetRegionChina WidgetRegion = "china"` - `Secret string` Secret key for this widget. - `Sitekey string` Widget item identifier tag. ### Example ```go 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) } ``` #### Response ```json { "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" }, "result_info": { "count": 1, "page": 1, "per_page": 20, "total_count": 2000 } } ``` ## Update a Turnstile Widget `client.Turnstile.Widgets.Update(ctx, sitekey, params) (*Widget, error)` **put** `/accounts/{account_id}/challenges/widgets/{sitekey}` Update the configuration of a widget. ### Parameters - `sitekey string` Widget item identifier tag. - `params WidgetUpdateParams` - `AccountID param.Field[string]` Path param: Identifier - `Domains param.Field[[]WidgetDomain]` Body param - `Mode param.Field[WidgetUpdateParamsMode]` Body param: Widget Mode - `const WidgetUpdateParamsModeNonInteractive WidgetUpdateParamsMode = "non-interactive"` - `const WidgetUpdateParamsModeInvisible WidgetUpdateParamsMode = "invisible"` - `const WidgetUpdateParamsModeManaged WidgetUpdateParamsMode = "managed"` - `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. - `BotFightMode param.Field[bool]` Body param: If bot_fight_mode is set to `true`, Cloudflare issues computationally expensive challenges in response to malicious bots (ENT only). - `ClearanceLevel param.Field[WidgetUpdateParamsClearanceLevel]` 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 WidgetUpdateParamsClearanceLevelNoClearance WidgetUpdateParamsClearanceLevel = "no_clearance"` - `const WidgetUpdateParamsClearanceLevelJschallenge WidgetUpdateParamsClearanceLevel = "jschallenge"` - `const WidgetUpdateParamsClearanceLevelManaged WidgetUpdateParamsClearanceLevel = "managed"` - `const WidgetUpdateParamsClearanceLevelInteractive WidgetUpdateParamsClearanceLevel = "interactive"` - `EphemeralID param.Field[bool]` Body param: Return the Ephemeral ID in /siteverify (ENT only). - `Offlabel param.Field[bool]` Body param: Do not show any Cloudflare branding on the widget (ENT only). - `Region param.Field[WidgetUpdateParamsRegion]` Body param: Region where this widget can be used. This cannot be changed after creation. - `const WidgetUpdateParamsRegionWorld WidgetUpdateParamsRegion = "world"` - `const WidgetUpdateParamsRegionChina WidgetUpdateParamsRegion = "china"` ### Returns - `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). - `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 - `const WidgetClearanceLevelNoClearance WidgetClearanceLevel = "no_clearance"` - `const WidgetClearanceLevelJschallenge WidgetClearanceLevel = "jschallenge"` - `const WidgetClearanceLevelManaged WidgetClearanceLevel = "managed"` - `const WidgetClearanceLevelInteractive WidgetClearanceLevel = "interactive"` - `CreatedOn Time` When the widget was created. - `Domains []WidgetDomain` - `EphemeralID bool` Return the Ephemeral ID in /siteverify (ENT only). - `Mode WidgetMode` Widget Mode - `const WidgetModeNonInteractive WidgetMode = "non-interactive"` - `const WidgetModeInvisible WidgetMode = "invisible"` - `const WidgetModeManaged WidgetMode = "managed"` - `ModifiedOn Time` When the widget was modified. - `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. - `Offlabel bool` Do not show any Cloudflare branding on the widget (ENT only). - `Region WidgetRegion` Region where this widget can be used. This cannot be changed after creation. - `const WidgetRegionWorld WidgetRegion = "world"` - `const WidgetRegionChina WidgetRegion = "china"` - `Secret string` Secret key for this widget. - `Sitekey string` Widget item identifier tag. ### Example ```go 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.Update( context.TODO(), "0x4AAF00AAAABn0R22HWm-YUc", turnstile.WidgetUpdateParams{ AccountID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"), Domains: cloudflare.F([]turnstile.WidgetDomainParam{"203.0.113.1", "cloudflare.com", "blog.example.com"}), Mode: cloudflare.F(turnstile.WidgetUpdateParamsModeInvisible), Name: cloudflare.F("blog.cloudflare.com login form"), }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", widget.EphemeralID) } ``` #### Response ```json { "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" } } ``` ## Delete a Turnstile Widget `client.Turnstile.Widgets.Delete(ctx, sitekey, body) (*Widget, error)` **delete** `/accounts/{account_id}/challenges/widgets/{sitekey}` Destroy a Turnstile Widget. ### Parameters - `sitekey string` Widget item identifier tag. - `body WidgetDeleteParams` - `AccountID param.Field[string]` Identifier ### Returns - `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). - `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 - `const WidgetClearanceLevelNoClearance WidgetClearanceLevel = "no_clearance"` - `const WidgetClearanceLevelJschallenge WidgetClearanceLevel = "jschallenge"` - `const WidgetClearanceLevelManaged WidgetClearanceLevel = "managed"` - `const WidgetClearanceLevelInteractive WidgetClearanceLevel = "interactive"` - `CreatedOn Time` When the widget was created. - `Domains []WidgetDomain` - `EphemeralID bool` Return the Ephemeral ID in /siteverify (ENT only). - `Mode WidgetMode` Widget Mode - `const WidgetModeNonInteractive WidgetMode = "non-interactive"` - `const WidgetModeInvisible WidgetMode = "invisible"` - `const WidgetModeManaged WidgetMode = "managed"` - `ModifiedOn Time` When the widget was modified. - `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. - `Offlabel bool` Do not show any Cloudflare branding on the widget (ENT only). - `Region WidgetRegion` Region where this widget can be used. This cannot be changed after creation. - `const WidgetRegionWorld WidgetRegion = "world"` - `const WidgetRegionChina WidgetRegion = "china"` - `Secret string` Secret key for this widget. - `Sitekey string` Widget item identifier tag. ### Example ```go 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.Delete( context.TODO(), "0x4AAF00AAAABn0R22HWm-YUc", turnstile.WidgetDeleteParams{ AccountID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"), }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", widget.EphemeralID) } ``` #### Response ```json { "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" } } ``` ## Rotate Secret for a Turnstile Widget `client.Turnstile.Widgets.RotateSecret(ctx, sitekey, params) (*Widget, error)` **post** `/accounts/{account_id}/challenges/widgets/{sitekey}/rotate_secret` Generate a new secret key for this widget. If `invalidate_immediately` is set to `false`, the previous secret remains valid for 2 hours. Note that secrets cannot be rotated again during the grace period. ### Parameters - `sitekey string` Widget item identifier tag. - `params WidgetRotateSecretParams` - `AccountID param.Field[string]` Path param: Identifier - `InvalidateImmediately param.Field[bool]` Body param: If `invalidate_immediately` is set to `false`, the previous secret will remain valid for two hours. Otherwise, the secret is immediately invalidated, and requests using it will be rejected. ### Returns - `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). - `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 - `const WidgetClearanceLevelNoClearance WidgetClearanceLevel = "no_clearance"` - `const WidgetClearanceLevelJschallenge WidgetClearanceLevel = "jschallenge"` - `const WidgetClearanceLevelManaged WidgetClearanceLevel = "managed"` - `const WidgetClearanceLevelInteractive WidgetClearanceLevel = "interactive"` - `CreatedOn Time` When the widget was created. - `Domains []WidgetDomain` - `EphemeralID bool` Return the Ephemeral ID in /siteverify (ENT only). - `Mode WidgetMode` Widget Mode - `const WidgetModeNonInteractive WidgetMode = "non-interactive"` - `const WidgetModeInvisible WidgetMode = "invisible"` - `const WidgetModeManaged WidgetMode = "managed"` - `ModifiedOn Time` When the widget was modified. - `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. - `Offlabel bool` Do not show any Cloudflare branding on the widget (ENT only). - `Region WidgetRegion` Region where this widget can be used. This cannot be changed after creation. - `const WidgetRegionWorld WidgetRegion = "world"` - `const WidgetRegionChina WidgetRegion = "china"` - `Secret string` Secret key for this widget. - `Sitekey string` Widget item identifier tag. ### Example ```go 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.RotateSecret( context.TODO(), "0x4AAF00AAAABn0R22HWm-YUc", turnstile.WidgetRotateSecretParams{ AccountID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"), }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", widget.EphemeralID) } ``` #### Response ```json { "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" } } ``` ## Domain Types ### Widget - `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). - `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 - `const WidgetClearanceLevelNoClearance WidgetClearanceLevel = "no_clearance"` - `const WidgetClearanceLevelJschallenge WidgetClearanceLevel = "jschallenge"` - `const WidgetClearanceLevelManaged WidgetClearanceLevel = "managed"` - `const WidgetClearanceLevelInteractive WidgetClearanceLevel = "interactive"` - `CreatedOn Time` When the widget was created. - `Domains []WidgetDomain` - `EphemeralID bool` Return the Ephemeral ID in /siteverify (ENT only). - `Mode WidgetMode` Widget Mode - `const WidgetModeNonInteractive WidgetMode = "non-interactive"` - `const WidgetModeInvisible WidgetMode = "invisible"` - `const WidgetModeManaged WidgetMode = "managed"` - `ModifiedOn Time` When the widget was modified. - `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. - `Offlabel bool` Do not show any Cloudflare branding on the widget (ENT only). - `Region WidgetRegion` Region where this widget can be used. This cannot be changed after creation. - `const WidgetRegionWorld WidgetRegion = "world"` - `const WidgetRegionChina WidgetRegion = "china"` - `Secret string` Secret key for this widget. - `Sitekey string` Widget item identifier tag. ### Widget Domain - `type WidgetDomain string` Hosts as a hostname or IPv4/IPv6 address represented by strings. The widget will only work on these domains, and their subdomains.