List roles
GET /v1/roles
Get a paginated list of roles.
Token scope required: roles:list
Request
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
orprevCursor
of a prior requestExample: bmV4dA.eyJsb2dzLmNyZQ5iIiwiX3ZhbHVlIjo9In19 - pageSize integer
Possible values:
<= 500
Default value:
25
Number of records to return in each page
- 200
Successful operation
- application/json
- Schema
- Example (from schema)
- noParams
- includeCounts
Schema
data object[]
Array [id stringname stringdescription stringfirewallRules object[]
Array [protocol string requiredPossible values: [
ANY
,TCP
,UDP
,ICMP
]description stringPossible values:
<= 255 characters
allowedRoleID string nullableRole ID to allow with this firewall rule. If not specified, all roles are included.
allowedTags key:value[]Tags to allow with this firewall rule. An empty list allows all tags. key is max 20 characters, value is max 50 characters, no whitespace around either allowed
portRange object nullable
Range of ports for this firewall rule. If not provided or set to null, all ports are allowed.
from integer requiredPossible values:
>= 1
and<= 65535
First port number included in range.
to integer requiredPossible values:
>= 1
and<= 65535
Last port number included in range. Must be greater than
from
port.]createdAt date-timemodifiedAt date-time]metadata object
totalCount integerThe total number of resources existing in the account
hasNextPage booleanIs there a page of data that can be fetched using the
nextCursor
?hasPrevPage booleanIs there a page of data that can be fetched using the
prevCursor
?nextCursor stringAn opaque string that can be used to fetch the next page of results. Not provided if result set is empty.
prevCursor stringAn opaque string that can be used to fetch the next page of results. Not provided if result set is empty.
page object
count integer requiredThe number of results returned in the response.
start integer requiredThe zero-based index of the first result within the overall list. For example, the first page will have a
start
of0
. If 25 results are fetched, and thenextCursor
used to fetch a new page of results, the second request'sstart
will be25
.
{
"data": [
{
"id": "string",
"name": "string",
"description": "string",
"firewallRules": [
{
"protocol": "ANY",
"description": "string",
"allowedRoleID": "string",
"allowedTags": [
"string"
],
"portRange": {
"from": 0,
"to": 0
}
}
],
"createdAt": "2024-03-28T12:39:11.029Z",
"modifiedAt": "2024-03-28T12:39:11.029Z"
}
],
"metadata": {
"totalCount": 0,
"hasNextPage": true,
"hasPrevPage": true,
"nextCursor": "string",
"prevCursor": "string",
"page": {
"count": 0,
"start": 0
}
}
}
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",
"firewallRules": [
{
"protocol": "TCP",
"description": "allow SSH access",
"allowedRoleID": "role-G3TWUQ4FASQEF44MGMTSRBTYKM",
"portRange": {
"from": 22,
"to": 22
}
}
]
}
],
"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",
"firewallRules": [
{
"protocol": "TCP",
"description": "allow SSH access",
"allowedRoleID": "role-G3TWUQ4FASQEF44MGMTSRBTYKM",
"portRange": {
"from": 22,
"to": 22
}
}
]
}
],
"metadata": {
"totalCount": 500,
"hasNextPage": true,
"hasPrevPage": true,
"prevCursor": "cHJldg.SI6ImIiLCJfdmFsdWUiOiI0dDVuREQreU",
"nextCursor": "bmV4dA.bHVlIjoieGJVS0UvYkRjQmZsY1pUbGJCc",
"page": {
"count": 1,
"start": 5
}
}
}