Interface ITurnstileApi

Namespace

Cloudflare.NET.Turnstile

Assembly

Cloudflare.NET.dll

Provides access to Cloudflare Turnstile API operations.

Turnstile is Cloudflare's CAPTCHA alternative that provides bot protection without user friction. Widgets are account-scoped and can be configured with different modes (invisible, managed, non-interactive).

public interface ITurnstileApi

Examples

// Create a widget
var widget = await client.Turnstile.CreateWidgetAsync(accountId,
  new CreateTurnstileWidgetRequest(
    Name: "Login Widget",
    Domains: new[] { "example.com", "www.example.com" },
    Mode: WidgetMode.Managed));

// Store the secret securely - it won't be available again!
var secret = widget.Secret;

// Later, rotate the secret
var result = await client.Turnstile.RotateSecretAsync(accountId, widget.Sitekey);
var newSecret = result.Secret;

Remarks

Turnstile is a separate Cloudflare product from the core API, with its own dedicated interface following the Interface Segregation Principle.

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

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.

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.

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.

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.

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.

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.

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.

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.