Interface IRolesApi

Namespace

Cloudflare.NET.Roles

Assembly

Cloudflare.NET.dll

Provides access to Cloudflare Account Roles API.

Roles are predefined by Cloudflare and define sets of permissions that can be assigned to account members. This API is read-only; roles cannot be created, modified, or deleted via the API.

public interface IRolesApi

Examples

// List all available roles
await foreach (var role in client.Roles.ListAllAccountRolesAsync(accountId))
{
  Console.WriteLine($"{role.Name}: {role.Description}");

  // Check specific permissions
  if (role.Permissions.Dns?.Write == true)
    Console.WriteLine("  - Can modify DNS");
}

Remarks

Common roles include "Administrator", "Administrator Read Only", "DNS Administrator", "Audit Log Viewer", and "Billing". Actual available roles depend on account type and plan.

Role IDs from this API are used when assigning roles to account members via the IMembersApi.

Methods

GetAccountRoleAsync(string, string, CancellationToken)

Gets details for a specific role.

Task<AccountRole> GetAccountRoleAsync(string accountId, string roleId, CancellationToken cancellationToken = default)

Parameters

accountId string

The account identifier.

roleId string

The role identifier.

cancellationToken CancellationToken

A cancellation token.

Returns

Task<AccountRole>

The role details including permissions.

Examples

var role = await client.Roles.GetAccountRoleAsync(accountId, roleId);
Console.WriteLine($"Role: {role.Name}");
Console.WriteLine($"Description: {role.Description}");

// Check DNS permissions
if (role.Permissions.DnsRecords is { Read: true, Write: true })
  Console.WriteLine("Has full DNS access");

Exceptions

ArgumentNullException

Thrown when accountId or roleId is null.

ArgumentException

Thrown when accountId or roleId is empty or whitespace.

HttpRequestException

Thrown when the role is not found (HTTP 404).

ListAccountRolesAsync(string, ListAccountRolesFilters?, CancellationToken)

Lists all roles available in the account.

Roles are predefined by Cloudflare and define sets of permissions that can be assigned to account members.

Task<PagePaginatedResult<AccountRole>> ListAccountRolesAsync(string accountId, ListAccountRolesFilters? filters = null, CancellationToken cancellationToken = default)

Parameters

accountId string

The account identifier.

filters ListAccountRolesFilters

Optional pagination options.

cancellationToken CancellationToken

A cancellation token.

Returns

Task<PagePaginatedResult<AccountRole>>

A page of account roles.

Examples

var roles = await client.Roles.ListAccountRolesAsync(accountId);

foreach (var role in roles.Items)
{
  Console.WriteLine($"{role.Name}: {role.Description}");
  if (role.Permissions.Dns?.Write == true)
    Console.WriteLine("  - Can modify DNS");
}

Exceptions

ArgumentNullException

Thrown when accountId is null.

ArgumentException

Thrown when accountId is empty or whitespace.

ListAllAccountRolesAsync(string, ListAccountRolesFilters?, CancellationToken)

Lists all roles available in the account, automatically handling pagination.

IAsyncEnumerable<AccountRole> ListAllAccountRolesAsync(string accountId, ListAccountRolesFilters? filters = null, CancellationToken cancellationToken = default)

Parameters

accountId string

The account identifier.

filters ListAccountRolesFilters

Optional pagination options. Pagination parameters are ignored.

cancellationToken CancellationToken

A cancellation token.

Returns

IAsyncEnumerable<AccountRole>

An async enumerable of all account roles.

Examples

// Iterate through all roles without manual pagination
await foreach (var role in client.Roles.ListAllAccountRolesAsync(accountId))
{
  Console.WriteLine($"{role.Id}: {role.Name}");
}

Exceptions

ArgumentNullException

Thrown when accountId is null.

ArgumentException

Thrown when accountId is empty or whitespace.