Class TurnstileApi

Namespace

Cloudflare.NET.Turnstile

Assembly

Cloudflare.NET.dll

Implementation of ITurnstileApi for Cloudflare Turnstile widgets.

Provides CRUD operations for managing Turnstile CAPTCHA widgets, including secret rotation for credential management.

public class TurnstileApi : ApiResource, ITurnstileApi

Inheritance

object

ApiResource

TurnstileApi

Implements

ITurnstileApi

Inherited Members

ApiResource.HttpClient

ApiResource.Logger

ApiResource.GetAsync<TResult>(string, CancellationToken)

ApiResource.GetAsync<TResult>(string, IEnumerable<KeyValuePair<string, string>>, CancellationToken)

ApiResource.PostAsync<TResult>(string, object, CancellationToken)

ApiResource.PutAsync<TResult>(string, object, CancellationToken)

ApiResource.PutAsync<TResult>(string, object, IEnumerable<KeyValuePair<string, string>>, CancellationToken)

ApiResource.PostAsync<TResult>(string, object, IEnumerable<KeyValuePair<string, string>>, CancellationToken)

ApiResource.PostJsonAsync<TResult>(string, string, CancellationToken)

ApiResource.PutJsonAsync<TResult>(string, string, CancellationToken)

ApiResource.PutJsonAsync<TResult>(string, string, IEnumerable<KeyValuePair<string, string>>, CancellationToken)

ApiResource.PatchAsync<TResult>(string, object, CancellationToken)

ApiResource.PatchAsync<TResult>(string, object, IEnumerable<KeyValuePair<string, string>>, CancellationToken)

ApiResource.DeleteAsync<TResult>(string, CancellationToken)

ApiResource.DeleteAsync<TResult>(string, IEnumerable<KeyValuePair<string, string>>, CancellationToken)

ApiResource.GetStringAsync(string, CancellationToken)

ApiResource.PostMultipartFileAsync<TResult>(string, Stream, string, string, CancellationToken)

ApiResource.GetPagePaginatedResultAsync<TItem>(string, CancellationToken)

ApiResource.GetCursorPaginatedResultAsync<TItem>(string, CancellationToken)

ApiResource.GetCursorPaginatedResultAsync<TWrapper, TItem>(string, Func<TWrapper, IReadOnlyList<TItem>>, CancellationToken)

ApiResource.GetCursorPaginatedResultAsync<TWrapper, TItem>(string, Func<TWrapper, IReadOnlyList<TItem>>, IEnumerable<KeyValuePair<string, string>>, CancellationToken)

ApiResource.GetPaginatedAsync<TItem>(string, int?, CancellationToken)

ApiResource.GetCursorPaginatedAsync<TItem>(string, int?, CancellationToken)

ApiResource.GetCursorPaginatedAsync<TWrapper, TItem>(string, int?, Func<TWrapper, IReadOnlyList<TItem>>, CancellationToken)

ApiResource.GetCursorPaginatedAsync<TWrapper, TItem>(string, int?, Func<TWrapper, IReadOnlyList<TItem>>, IEnumerable<KeyValuePair<string, string>>, CancellationToken)

ApiResource.ProcessResponse<T>(HttpResponseMessage, CancellationToken)

ApiResource.ProcessAndDeserializeAsync<T>(HttpResponseMessage, CancellationToken)

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

Important: Widget secrets are only returned on creation and rotation. Store them securely as they cannot be retrieved again.

Constructors

TurnstileApi(HttpClient, ILoggerFactory)

Initializes a new instance of the TurnstileApi class.

public TurnstileApi(HttpClient httpClient, ILoggerFactory loggerFactory)

Parameters

httpClient HttpClient

The HttpClient for making requests.

loggerFactory ILoggerFactory

The factory to create loggers for this resource.

Methods

CreateWidgetAsync(string, CreateTurnstileWidgetRequest, CancellationToken)

Creates a new Turnstile widget.

The response includes the secret key which is only returned at creation time. Store it securely as it cannot be retrieved again.

public Task<TurnstileWidget> CreateWidgetAsync(string accountId, CreateTurnstileWidgetRequest request, CancellationToken cancellationToken = default)

Parameters

accountId string

The account identifier.

request CreateTurnstileWidgetRequest

The widget creation parameters.

cancellationToken CancellationToken

A cancellation token.

Returns

Task<TurnstileWidget>

The created widget including the secret key.

Examples

var widget = await client.Turnstile.CreateWidgetAsync(accountId,
  new CreateTurnstileWidgetRequest(
    Name: "Contact Form",
    Domains: new[] { "example.com" },
    Mode: WidgetMode.Invisible,
    BotFightMode: true));

// IMPORTANT: Store the secret securely!
SaveSecurely(widget.Secret);

Exceptions

ArgumentException

Thrown when accountId is null or whitespace.

ArgumentNullException

Thrown when request is null.

DeleteWidgetAsync(string, string, CancellationToken)

Deletes a Turnstile widget.

public Task DeleteWidgetAsync(string accountId, string sitekey, CancellationToken cancellationToken = default)

Parameters

accountId string

The account identifier.

sitekey string

The widget sitekey.

cancellationToken CancellationToken

A cancellation token.

Returns

Task

Examples

await client.Turnstile.DeleteWidgetAsync(accountId, sitekey);
Console.WriteLine($"Deleted widget: {sitekey}");

Exceptions

ArgumentException

Thrown when accountId or sitekey is null or whitespace.

GetWidgetAsync(string, string, CancellationToken)

Gets details for a specific Turnstile widget.

public Task<TurnstileWidget> GetWidgetAsync(string accountId, string sitekey, CancellationToken cancellationToken = default)

Parameters

accountId string

The account identifier.

sitekey string

The widget sitekey (public key).

cancellationToken CancellationToken

A cancellation token.

Returns

Task<TurnstileWidget>

The widget details (without the secret).

Examples

var widget = await client.Turnstile.GetWidgetAsync(accountId, sitekey);
Console.WriteLine($"Mode: {widget.Mode}, Domains: {string.Join(", ", widget.Domains)}");

Exceptions

ArgumentException

Thrown when accountId or sitekey is null or whitespace.

ListAllWidgetsAsync(string, ListTurnstileWidgetsFilters?, CancellationToken)

Lists all Turnstile widgets, automatically handling pagination.

public IAsyncEnumerable<TurnstileWidget> ListAllWidgetsAsync(string accountId, ListTurnstileWidgetsFilters? filters = null, CancellationToken cancellationToken = default)

Parameters

accountId string

The account identifier.

filters ListTurnstileWidgetsFilters

Optional filtering options (Page is ignored).

cancellationToken CancellationToken

A cancellation token.

Returns

IAsyncEnumerable<TurnstileWidget>

An async enumerable of all widgets.

Examples

await foreach (var widget in client.Turnstile.ListAllWidgetsAsync(accountId))
{
  Console.WriteLine($"{widget.Name}: {widget.Mode}");
}

Exceptions

ArgumentException

Thrown when accountId is null or whitespace.

ListWidgetsAsync(string, ListTurnstileWidgetsFilters?, CancellationToken)

Lists all Turnstile widgets for the account.

public Task<PagePaginatedResult<TurnstileWidget>> ListWidgetsAsync(string accountId, ListTurnstileWidgetsFilters? filters = null, CancellationToken cancellationToken = default)

Parameters

accountId string

The account identifier.

filters ListTurnstileWidgetsFilters

Optional filtering and pagination options.

cancellationToken CancellationToken

A cancellation token.

Returns

Task<PagePaginatedResult<TurnstileWidget>>

A paginated result containing widgets.

Examples

var result = await client.Turnstile.ListWidgetsAsync(accountId,
  new ListTurnstileWidgetsFilters(
    Order: TurnstileOrderField.CreatedOn,
    Direction: ListOrderDirection.Desc));

foreach (var widget in result.Result)
{
  Console.WriteLine($"{widget.Name}: {widget.Sitekey}");
}

Exceptions

ArgumentException

Thrown when accountId is null or whitespace.

RotateSecretAsync(string, string, bool, CancellationToken)

Rotates a widget's secret key.

By default, the old secret remains valid for 2 hours to allow graceful migration. Set invalidateImmediately to true to revoke the old secret immediately.

public Task<RotateWidgetSecretResult> RotateSecretAsync(string accountId, string sitekey, bool invalidateImmediately = false, CancellationToken cancellationToken = default)

Parameters

accountId string

The account identifier.

sitekey string

The widget sitekey.

invalidateImmediately bool

If true, invalidates the old secret immediately. If false (default), old secret remains valid for 2 hours.

cancellationToken CancellationToken

A cancellation token.

Returns

Task<RotateWidgetSecretResult>

The result containing the new secret key.

Examples

// Rotate with 2-hour grace period (default)
var result = await client.Turnstile.RotateSecretAsync(accountId, sitekey);

// Or invalidate old secret immediately
var result = await client.Turnstile.RotateSecretAsync(accountId, sitekey, invalidateImmediately: true);

// Store the new secret securely
UpdateStoredSecret(result.Secret);

Exceptions

ArgumentException

Thrown when accountId or sitekey is null or whitespace.

UpdateWidgetAsync(string, string, UpdateTurnstileWidgetRequest, CancellationToken)

Updates an existing Turnstile widget.

public Task<TurnstileWidget> UpdateWidgetAsync(string accountId, string sitekey, UpdateTurnstileWidgetRequest request, CancellationToken cancellationToken = default)

Parameters

accountId string

The account identifier.

sitekey string

The widget sitekey.

request UpdateTurnstileWidgetRequest

The update parameters.

cancellationToken CancellationToken

A cancellation token.

Returns

Task<TurnstileWidget>

The updated widget.

Examples

var updated = await client.Turnstile.UpdateWidgetAsync(accountId, sitekey,
  new UpdateTurnstileWidgetRequest(
    Name: "Updated Name",
    Domains: new[] { "example.com", "api.example.com" },
    Mode: WidgetMode.Managed));

Exceptions

ArgumentException

Thrown when accountId or sitekey is null or whitespace.

ArgumentNullException

Thrown when request is null.