Class ApiTokensApi

Namespace

Cloudflare.NET.ApiTokens

Assembly

Cloudflare.NET.dll

Implements the API for managing Cloudflare API tokens.

API tokens provide fine-grained access control for Cloudflare API operations. Each token has policies that define what resources and actions are allowed.

public class ApiTokensApi : ApiResource, IApiTokensApi

Inheritance

object

ApiResource

ApiTokensApi

Implements

IApiTokensApi

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()

Constructors

ApiTokensApi(HttpClient, ILoggerFactory)

Initializes a new instance of the ApiTokensApi class.

public ApiTokensApi(HttpClient httpClient, ILoggerFactory loggerFactory)

Parameters

httpClient HttpClient

The HttpClient for making requests.

loggerFactory ILoggerFactory

The factory to create loggers for this resource.

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.

public 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.

public 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.

public 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.

public 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.

public 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.

public 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.

public 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.

public 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.

public 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.

public 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.

public 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.

public 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.

public 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.

public 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.

public 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.

public 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.

public 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.

public 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.

public 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.

public 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}");