Interface IApiTokensApi

Namespace

Cloudflare.NET.ApiTokens

Assembly

Cloudflare.NET.dll

Defines the contract for API token management operations.

API tokens provide fine-grained access control for Cloudflare API operations. This interface handles account-scoped tokens. User-scoped tokens will be added in F17.

public interface IApiTokensApi

Examples

// Create a new token
var result = await client.ApiTokens.CreateAccountTokenAsync(accountId,
  new CreateApiTokenRequest(
    Name: "CI/CD Token",
    Policies: new[]
    {
      new CreateTokenPolicyRequest(
        Effect: "allow",
        PermissionGroups: new[] { new TokenPermissionGroupReference(permissionGroupId) },
        Resources: new Dictionary<string, string>
        {
          ["com.cloudflare.api.account.*"] = "*"
        })
    }));

// Store the token value securely - it cannot be retrieved again!
Console.WriteLine($"Token: {result.Value}");

// Later, roll the token to generate a new secret
var newValue = await client.ApiTokens.RollAccountTokenAsync(accountId, result.Id);

Remarks

Key features of API tokens:

• Policy-based access control with allow/deny effects
• IP address restrictions using CIDR notation
• Time-bounded validity with not_before and expires_on
• Secret rotation without recreating the token

Methods

CreateAccountTokenAsync(string, CreateApiTokenRequest, CancellationToken)

Creates a new API token.

Important: The returned Value contains the token secret. Store it securely - it cannot be retrieved again.

Task<CreateApiTokenResult> CreateAccountTokenAsync(string accountId, CreateApiTokenRequest request, CancellationToken cancellationToken = default)

Parameters

accountId string

The account identifier.

request CreateApiTokenRequest

The token creation parameters.

cancellationToken CancellationToken

A cancellation token.

Returns

Task<CreateApiTokenResult>

The created token including its secret value.

Examples

var result = await client.ApiTokens.CreateAccountTokenAsync(accountId,
  new CreateApiTokenRequest(
    Name: "CI/CD Token",
    Policies: new[]
    {
      new CreateTokenPolicyRequest(
        Effect: "allow",
        PermissionGroups: new[] { new TokenPermissionGroupReference("...") },
        Resources: new Dictionary<string, string>
        {
          ["com.cloudflare.api.account.*"] = "*"
        })
    },
    ExpiresOn: DateTime.UtcNow.AddYears(1)));

Console.WriteLine($"Token: {result.Value}"); // Store securely!

Exceptions

ArgumentException

Thrown when accountId is null or whitespace.

ArgumentNullException

Thrown when request is null.

CreateUserTokenAsync(CreateApiTokenRequest, CancellationToken)

Creates a new API token for the authenticated user.

Important: The returned Value contains the token secret. Store it securely - it cannot be retrieved again.

Task<CreateApiTokenResult> CreateUserTokenAsync(CreateApiTokenRequest request, CancellationToken cancellationToken = default)

Parameters

request CreateApiTokenRequest

The token creation parameters.

cancellationToken CancellationToken

A cancellation token.

Returns

Task<CreateApiTokenResult>

The created token including its secret value.

Examples

var result = await client.ApiTokens.CreateUserTokenAsync(
  new CreateApiTokenRequest(
    Name: "Personal Token",
    Policies: new[]
    {
      new CreateTokenPolicyRequest(
        Effect: "allow",
        PermissionGroups: new[] { new TokenPermissionGroupReference("...") },
        Resources: new Dictionary<string, string>
        {
          ["com.cloudflare.api.user"] = "*"
        })
    },
    ExpiresOn: DateTime.UtcNow.AddYears(1)));

Console.WriteLine($"Token: {result.Value}"); // Store securely!

Exceptions

ArgumentNullException

Thrown when request is null.

DeleteAccountTokenAsync(string, string, CancellationToken)

Deletes an API token.

Task DeleteAccountTokenAsync(string accountId, string tokenId, CancellationToken cancellationToken = default)

Parameters

accountId string

The account identifier.

tokenId string

The token identifier.

cancellationToken CancellationToken

A cancellation token.

Returns

Task

Examples

await client.ApiTokens.DeleteAccountTokenAsync(accountId, tokenId);

Exceptions

ArgumentException

Thrown when accountId or tokenId is null or whitespace.

DeleteUserTokenAsync(string, CancellationToken)

Deletes an API token.

Task DeleteUserTokenAsync(string tokenId, CancellationToken cancellationToken = default)

Parameters

tokenId string

The token identifier.

cancellationToken CancellationToken

A cancellation token.

Returns

Task

Examples

await client.ApiTokens.DeleteUserTokenAsync(tokenId);

Exceptions

ArgumentException

Thrown when tokenId is null or whitespace.

GetAccountPermissionGroupsAsync(string, ListPermissionGroupsFilters?, CancellationToken)

Lists available permission groups for API tokens.

Task<PagePaginatedResult<PermissionGroup>> GetAccountPermissionGroupsAsync(string accountId, ListPermissionGroupsFilters? filters = null, CancellationToken cancellationToken = default)

Parameters

accountId string

The account identifier.

filters ListPermissionGroupsFilters

Optional filtering options.

cancellationToken CancellationToken

A cancellation token.

Returns

Task<PagePaginatedResult<PermissionGroup>>

A page of permission groups.

Examples

var result = await client.ApiTokens.GetAccountPermissionGroupsAsync(accountId);
foreach (var group in result.Items)
{
  Console.WriteLine($"{group.Name} ({group.Id})");
}

Exceptions

ArgumentException

Thrown when accountId is null or whitespace.

GetAccountTokenAsync(string, string, CancellationToken)

Gets details for a specific API token.

Task<ApiToken> GetAccountTokenAsync(string accountId, string tokenId, CancellationToken cancellationToken = default)

Parameters

accountId string

The account identifier.

tokenId string

The token identifier.

cancellationToken CancellationToken

A cancellation token.

Returns

Task<ApiToken>

The API token details.

Examples

var token = await client.ApiTokens.GetAccountTokenAsync(accountId, tokenId);
Console.WriteLine($"Token: {token.Name}");
Console.WriteLine($"Status: {token.Status}");
Console.WriteLine($"Expires: {token.ExpiresOn}");

Exceptions

ArgumentException

Thrown when accountId or tokenId is null or whitespace.

GetAllAccountPermissionGroupsAsync(string, ListPermissionGroupsFilters?, CancellationToken)

Lists all available permission groups, automatically handling pagination.

IAsyncEnumerable<PermissionGroup> GetAllAccountPermissionGroupsAsync(string accountId, ListPermissionGroupsFilters? filters = null, CancellationToken cancellationToken = default)

Parameters

accountId string

The account identifier.

filters ListPermissionGroupsFilters

Optional filtering options.

cancellationToken CancellationToken

A cancellation token.

Returns

IAsyncEnumerable<PermissionGroup>

An async enumerable of all permission groups.

Examples

// Find permission groups for a specific scope
await foreach (var group in client.ApiTokens.GetAllAccountPermissionGroupsAsync(accountId))
{
  if (group.Scopes.Contains("zone:read"))
    Console.WriteLine($"Found group with zone:read: {group.Name}");
}

Exceptions

ArgumentException

Thrown when accountId is null or whitespace.

GetAllUserPermissionGroupsAsync(ListPermissionGroupsFilters?, CancellationToken)

Lists all available permission groups for user tokens, automatically handling pagination.

IAsyncEnumerable<PermissionGroup> GetAllUserPermissionGroupsAsync(ListPermissionGroupsFilters? filters = null, CancellationToken cancellationToken = default)

Parameters

filters ListPermissionGroupsFilters

Optional filtering options.

cancellationToken CancellationToken

A cancellation token.

Returns

IAsyncEnumerable<PermissionGroup>

An async enumerable of all permission groups.

Examples

// Find permission groups for a specific scope
await foreach (var group in client.ApiTokens.GetAllUserPermissionGroupsAsync())
{
  if (group.Scopes.Contains("zone:read"))
    Console.WriteLine($"Found group with zone:read: {group.Name}");
}

GetUserPermissionGroupsAsync(ListPermissionGroupsFilters?, CancellationToken)

Lists available permission groups for user API tokens.

Task<PagePaginatedResult<PermissionGroup>> GetUserPermissionGroupsAsync(ListPermissionGroupsFilters? filters = null, CancellationToken cancellationToken = default)

Parameters

filters ListPermissionGroupsFilters

Optional filtering options.

cancellationToken CancellationToken

A cancellation token.

Returns

Task<PagePaginatedResult<PermissionGroup>>

A page of permission groups.

Examples

var result = await client.ApiTokens.GetUserPermissionGroupsAsync();
foreach (var group in result.Items)
{
  Console.WriteLine($"{group.Name} ({group.Id})");
}

GetUserTokenAsync(string, CancellationToken)

Gets details for a specific API token.

Task<ApiToken> GetUserTokenAsync(string tokenId, CancellationToken cancellationToken = default)

Parameters

tokenId string

The token identifier.

cancellationToken CancellationToken

A cancellation token.

Returns

Task<ApiToken>

The API token details.

Examples

var token = await client.ApiTokens.GetUserTokenAsync(tokenId);
Console.WriteLine($"Token: {token.Name}");
Console.WriteLine($"Status: {token.Status}");
Console.WriteLine($"Expires: {token.ExpiresOn}");

Exceptions

ArgumentException

Thrown when tokenId is null or whitespace.

ListAccountTokensAsync(string, ListApiTokensFilters?, CancellationToken)

Lists all API tokens for the account.

Task<PagePaginatedResult<ApiToken>> ListAccountTokensAsync(string accountId, ListApiTokensFilters? filters = null, CancellationToken cancellationToken = default)

Parameters

accountId string

The account identifier.

filters ListApiTokensFilters

Optional filtering and pagination options.

cancellationToken CancellationToken

A cancellation token.

Returns

Task<PagePaginatedResult<ApiToken>>

A page of API tokens.

Examples

// Get first page of tokens
var result = await client.ApiTokens.ListAccountTokensAsync(accountId);
foreach (var token in result.Items)
{
  Console.WriteLine($"{token.Name}: {token.Status}");
}

Exceptions

ArgumentException

Thrown when accountId is null or whitespace.

ListAllAccountTokensAsync(string, ListApiTokensFilters?, CancellationToken)

Lists all API tokens for the account, automatically handling pagination.

IAsyncEnumerable<ApiToken> ListAllAccountTokensAsync(string accountId, ListApiTokensFilters? filters = null, CancellationToken cancellationToken = default)

Parameters

accountId string

The account identifier.

filters ListApiTokensFilters

Optional filtering options. Pagination parameters are managed internally.

cancellationToken CancellationToken

A cancellation token.

Returns

IAsyncEnumerable<ApiToken>

An async enumerable of all API tokens.

Examples

// Iterate through all tokens with automatic pagination
await foreach (var token in client.ApiTokens.ListAllAccountTokensAsync(accountId))
{
  Console.WriteLine($"{token.Name}: {token.Status}");
}

Exceptions

ArgumentException

Thrown when accountId is null or whitespace.

ListAllUserTokensAsync(ListApiTokensFilters?, CancellationToken)

Lists all API tokens for the authenticated user, automatically handling pagination.

IAsyncEnumerable<ApiToken> ListAllUserTokensAsync(ListApiTokensFilters? filters = null, CancellationToken cancellationToken = default)

Parameters

filters ListApiTokensFilters

Optional filtering options. Pagination parameters are managed internally.

cancellationToken CancellationToken

A cancellation token.

Returns

IAsyncEnumerable<ApiToken>

An async enumerable of all API tokens.

Examples

// Iterate through all tokens with automatic pagination
await foreach (var token in client.ApiTokens.ListAllUserTokensAsync())
{
  Console.WriteLine($"{token.Name}: {token.Status}");
}

ListUserTokensAsync(ListApiTokensFilters?, CancellationToken)

Lists all API tokens created by the authenticated user.

Task<PagePaginatedResult<ApiToken>> ListUserTokensAsync(ListApiTokensFilters? filters = null, CancellationToken cancellationToken = default)

Parameters

filters ListApiTokensFilters

Optional filtering and pagination options.

cancellationToken CancellationToken

A cancellation token.

Returns

Task<PagePaginatedResult<ApiToken>>

A page of API tokens.

Examples

// Get first page of user tokens
var result = await client.ApiTokens.ListUserTokensAsync();
foreach (var token in result.Items)
{
  Console.WriteLine($"{token.Name}: {token.Status}");
}

RollAccountTokenAsync(string, string, CancellationToken)

Rolls (rotates) a token's secret, generating a new value.

The old token value becomes invalid immediately. All clients using the old value must be updated with the new one.

Task<string> RollAccountTokenAsync(string accountId, string tokenId, CancellationToken cancellationToken = default)

Parameters

accountId string

The account identifier.

tokenId string

The token identifier.

cancellationToken CancellationToken

A cancellation token.

Returns

Task<string>

The new token secret value.

Examples

// Rotate the token secret
var newValue = await client.ApiTokens.RollAccountTokenAsync(accountId, tokenId);
Console.WriteLine($"New token value: {newValue}"); // Store securely!

Exceptions

ArgumentException

Thrown when accountId or tokenId is null or whitespace.

RollUserTokenAsync(string, CancellationToken)

Rolls (rotates) a token's secret, generating a new value.

The old token value becomes invalid immediately. All clients using the old value must be updated with the new one.

Task<string> RollUserTokenAsync(string tokenId, CancellationToken cancellationToken = default)

Parameters

tokenId string

The token identifier.

cancellationToken CancellationToken

A cancellation token.

Returns

Task<string>

The new token secret value.

Examples

// Rotate the token secret
var newValue = await client.ApiTokens.RollUserTokenAsync(tokenId);
Console.WriteLine($"New token value: {newValue}"); // Store securely!

Exceptions

ArgumentException

Thrown when tokenId is null or whitespace.

UpdateAccountTokenAsync(string, string, UpdateApiTokenRequest, CancellationToken)

Updates an existing API token.

Task<ApiToken> UpdateAccountTokenAsync(string accountId, string tokenId, UpdateApiTokenRequest request, CancellationToken cancellationToken = default)

Parameters

accountId string

The account identifier.

tokenId string

The token identifier.

request UpdateApiTokenRequest

The update parameters.

cancellationToken CancellationToken

A cancellation token.

Returns

Task<ApiToken>

The updated token.

Examples

// Disable a token
var updated = await client.ApiTokens.UpdateAccountTokenAsync(accountId, tokenId,
  new UpdateApiTokenRequest(
    Name: token.Name,
    Policies: token.Policies.Select(p => new CreateTokenPolicyRequest(
      p.Effect, p.PermissionGroups, p.Resources)).ToList(),
    Status: TokenStatus.Disabled));

Exceptions

ArgumentException

Thrown when accountId or tokenId is null or whitespace.

ArgumentNullException

Thrown when request is null.

UpdateUserTokenAsync(string, UpdateApiTokenRequest, CancellationToken)

Updates an existing API token.

Task<ApiToken> UpdateUserTokenAsync(string tokenId, UpdateApiTokenRequest request, CancellationToken cancellationToken = default)

Parameters

tokenId string

The token identifier.

request UpdateApiTokenRequest

The update parameters.

cancellationToken CancellationToken

A cancellation token.

Returns

Task<ApiToken>

The updated token.

Examples

// Disable a token
var updated = await client.ApiTokens.UpdateUserTokenAsync(tokenId,
  new UpdateApiTokenRequest(
    Name: token.Name,
    Policies: token.Policies.Select(p => new CreateTokenPolicyRequest(
      p.Effect, p.PermissionGroups, p.Resources)).ToList(),
    Status: TokenStatus.Disabled));

Exceptions

ArgumentException

Thrown when tokenId is null or whitespace.

ArgumentNullException

Thrown when request is null.

VerifyAccountTokenAsync(string, CancellationToken)

Verifies that the current token being used is valid and working.

Task<VerifyTokenResult> VerifyAccountTokenAsync(string accountId, CancellationToken cancellationToken = default)

Parameters

accountId string

The account identifier.

cancellationToken CancellationToken

A cancellation token.

Returns

Task<VerifyTokenResult>

Token verification status.

Examples

var result = await client.ApiTokens.VerifyAccountTokenAsync(accountId);
Console.WriteLine($"Token {result.Id} is {result.Status}");
if (result.ExpiresOn.HasValue)
  Console.WriteLine($"Expires: {result.ExpiresOn}");

Exceptions

ArgumentException

Thrown when accountId is null or whitespace.

VerifyUserTokenAsync(CancellationToken)

Verifies that the current token being used is valid and working.

This endpoint can be used to test whether a token is properly configured and has the expected permissions.

Task<VerifyTokenResult> VerifyUserTokenAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

A cancellation token.

Returns

Task<VerifyTokenResult>

Token verification status.

Examples

var result = await client.ApiTokens.VerifyUserTokenAsync();
Console.WriteLine($"Token {result.Id} is {result.Status}");
if (result.ExpiresOn.HasValue)
  Console.WriteLine($"Expires: {result.ExpiresOn}");