List roles

GET

/v1/roles

• Default server

Get a paginated list of roles.

Token scope required: roles:list

Authorizations

• ApiToken
  roles:list

Parameters

Query Parameters

includeCounts

boolean

If true, return count of total records and current page start and count in metadata

cursor

string

Cursor value at which to start the results, provided in nextCursor or prevCursor of a prior request

Example

bmV4dA.eyJsb2dzLmNyZQ5iIiwiX3ZhbHVlIjo9In19

pageSize

integer

default: 25 <= 500

Number of records to return in each page

sortDirection

string

default: asc

Allowed values: asc desc

Order in which to return results. Each endpoint sorts on its own key (for example, hosts by name and audit logs by creation time). Matching is case-insensitive, and any value other than desc sorts ascending.

Responses

200

Successful operation

object

data

required

Array<object>

object

id

required

string

name

required

string

description

required

string

firewallRulesCount

required

Number of inbound firewall rules configured on this role.

integer

hostCount

required

Number of hosts currently assigned to this role.

integer

createdAt

required

string format: date-time

modifiedAt

required

string format: date-time

metadata

required

object

totalCount

The total number of resources existing in the account. Only present when includeCounts is true.

integer

hasNextPage

required

Is there a page of data that can be fetched using the nextCursor?

boolean

hasPrevPage

required

Is there a page of data that can be fetched using the prevCursor?

boolean

nextCursor

An opaque string that can be used to fetch the next page of results. Not provided if result set is empty.

string

prevCursor

An opaque string that can be used to fetch the previous page of results. Not provided if result set is empty.

string

page

Only present when includeCounts is true.

object

count

required

The number of results returned in the response.

integer

start

required

The zero-based index of the first result within the overall list. For example, the first page will have a start of 0. If 25 results are fetched, and the nextCursor used to fetch a new page of results, the second request’s start will be 25.

integer

Examples

When includeCounts parameter is not set to true

{
  "data": [
    {
      "id": "role-LO4SPDSWTZNJC676WFCZKUB3ZQ",
      "name": "My new role",
      "description": "",
      "createdAt": "2023-02-15T13:59:09Z",
      "modifiedAt": "2023-02-15T13:59:09Z",
      "firewallRulesCount": 1,
      "hostCount": 3
    }
  ],
  "metadata": {
    "hasNextPage": true,
    "hasPrevPage": true,
    "nextCursor": "bmV4dA.bHVlIjoieGJVS0UvYkRjQmZsY1pUbGJCc",
    "prevCursor": "cHJldg.SI6ImIiLCJfdmFsdWUiOiI0dDVuREQreU"
  }
}

Metadata returned when including request params for includeCounts=true, pageSize=1, and cursor="somevalue".

{
  "data": [
    {
      "id": "role-LO4SPDSWTZNJC676WFCZKUB3ZQ",
      "name": "My new role",
      "description": "",
      "createdAt": "2023-02-15T13:59:09Z",
      "modifiedAt": "2023-02-15T13:59:09Z",
      "firewallRulesCount": 1,
      "hostCount": 3
    }
  ],
  "metadata": {
    "totalCount": 500,
    "hasNextPage": true,
    "hasPrevPage": true,
    "prevCursor": "cHJldg.SI6ImIiLCJfdmFsdWUiOiI0dDVuREQreU",
    "nextCursor": "bmV4dA.bHVlIjoieGJVS0UvYkRjQmZsY1pUbGJCc",
    "page": {
      "count": 1,
      "start": 5
    }
  }
}

401

The API key is missing, invalid or expired.

object

errors

required

Array<object>

object

code

required

A static name for the error type

string

message

required

A short human readable description of the error

string

path

Describes the variable missing or malformed

string

param

The query parameter the error relates to, such as filter.targetType

string

extra

Machine-readable details about the error. ERR_LIMIT_EXCEEDED errors carry limit and limitName.

object

limit

The maximum number of resources allowed

integer

limitName

The kind of resource the limit applies to

string

key

additional properties

any

Example

{
  "errors": [
    {
      "code": "ERR_UNAUTHORIZED",
      "message": "unauthorized"
    }
  ]
}

403

The API key lacks a required scope.

object

errors

required

Array<object>

object

code

required

A static name for the error type

string

message

required

A short human readable description of the error

string

path

Describes the variable missing or malformed

string

param

The query parameter the error relates to, such as filter.targetType

string

extra

Machine-readable details about the error. ERR_LIMIT_EXCEEDED errors carry limit and limitName.

object

limit

The maximum number of resources allowed

integer

limitName

The kind of resource the limit applies to

string

key

additional properties

any

Examples

The API key lacks a required scope.

{
  "errors": [
    {
      "code": "ERR_FORBIDDEN",
      "message": "api key must support the following scopes: hosts:read"
    }
  ]
}

429

The organization has exceeded its API request rate limit. Retry the request after a short delay.

object

errors

required

Array<object>

object

code

required

A static name for the error type

string

message

required

A short human readable description of the error

string

path

Describes the variable missing or malformed

string

param

The query parameter the error relates to, such as filter.targetType

string

extra

Machine-readable details about the error. ERR_LIMIT_EXCEEDED errors carry limit and limitName.

object

limit

The maximum number of resources allowed

integer

limitName

The kind of resource the limit applies to

string

key

additional properties

any

Example

{
  "errors": [
    {
      "code": "ERR_TOO_MANY_REQUESTS",
      "message": "too many requests"
    }
  ]
}