Docs/Admin API/Roles/List

List roles

Preview

GET/admin/v1/roles

List roles.

query parameters

pageSize
int32
The maximum number of roles to return. The API may return fewer than this value.
If unspecified, at most 20 roles will be returned. The maximum value is 100; values above 100 will be coerced to 100.
pageToken
string
A page token, received from a previous list roles call. Provide this to retrieve the subsequent page.
When paginating, all other parameters provided to list roles must match the call that provided the page token.
orderBy
string
A comma-separated list of fields to order by.

Returns

roles
Role[]
The list of roles.
id
string
The system-assigned identifier of the role.
uniqueId
string
The client defined unique identifier of the role.
It is restricted to letters, numbers, underscores, and hyphens, with the first character a letter or a number, and a 255 character maximum.
ID's starting with role_ are reserved.
displayName
string
The human-readable display name of the role.
type
enum
The role type.
Possible values:
OWNERMEMBERGUEST
description
string
The description of the role.
The maximum length is 1000 characters.
seatPolicy
enum
The policy that defines how a member is assigned a seat.
Possible values:
DEFAULTMANUAL
permissionSets
string[]
The additional permissions allowed by the role.
default
boolean
Whether the role is the default for the tenant.
archived
boolean
The archived status of the role.
view
enum
The role view.
Possible values:
BASICFULL
createTime
date-time
The creation time of the role.
updateTime
date-time
The last update time of the role.
nextPageToken
string
A token, which can be sent as pageToken to retrieve the next page. If this field is omitted, there are no subsequent pages.
previousPageToken
string
A token, which can be sent as pageToken to retrieve the previous page. If this field is absent, there are no preceding pages. If this field is an empty string then the previous page is the first result.

code
enum
The general error code (e.g. INVALID_ARGUMENT).
Possible values:
OKCANCELLEDUNKNOWNINVALID_ARGUMENTDEADLINE_EXCEEDEDNOT_FOUNDALREADY_EXISTSPERMISSION_DENIEDUNAUTHENTICATEDRESOURCE_EXHAUSTEDFAILED_PRECONDITIONABORTEDOUT_OF_RANGEUNIMPLEMENTEDINTERNALUNAVAILABLEDATA_LOSS
message
string
A developer-facing error message.
reason
string
A reason code for the error (e.g. USER_PENDING_DELETION).
param
string
The parameter path related to the error (e.g. member.userId).
metadata
string
Additional metadata related to the error.
localeMessage
string
A user-facing error message.

curl https://api.userhub.com/admin/v1/roles \
  -H "Authorization: Bearer $USERHUB_ADMIN_KEY"

const res = await adminApi.roles.list();

res, err := adminApi.Roles().List(
    context.Background(),
    nil,
)

$res = $adminApi->roles->list();

res = admin_api.roles.list()

Response bodyJSON

{
  "roles": [
    {
      "id": "role_2mD13uXP",
      "uniqueId": "member",
      "displayName": "Member",
      "type": "MEMBER",
      "description": "Can see every member in the organization",
      "seatPolicy": "DEFAULT",
      "permissionSets": [
        "members.invite"
      ],
      "default": true,
      "archived": false,
      "view": "BASIC",
      "createTime": "2025-05-15T13:00:00Z",
      "updateTime": "2025-05-15T13:00:00Z"
    },
    {
      "id": "role_51jav4KK",
      "uniqueId": "admin",
      "displayName": "Admin",
      "type": "MEMBER",
      "description": "Can manage members of the organization",
      "seatPolicy": "DEFAULT",
      "permissionSets": [
        "billing.readonly",
        "members.readwrite"
      ],
      "default": false,
      "archived": false,
      "view": "BASIC",
      "createTime": "2025-05-15T13:00:00Z",
      "updateTime": "2025-05-15T13:00:00Z"
    },
    {
      "id": "role_4NNSzkhn",
      "uniqueId": "owner",
      "displayName": "Owner",
      "type": "OWNER",
      "description": "Has full administrative access to the entire organization",
      "seatPolicy": "DEFAULT",
      "permissionSets": [],
      "default": false,
      "archived": false,
      "view": "BASIC",
      "createTime": "2025-05-15T13:00:00Z",
      "updateTime": "2025-05-15T13:00:00Z"
    }
  ]
}

PreviousThe role object

NextSubscriptions

List roles

.css-10iahqc{text-transform:capitalize;}query parameters

Returns

query parameters