Sign in
permissions

List roles

Retrieve all roles in your workspace including their assigned permissions. Results are paginated and sorted by their id.

Required Permissions

Your root key must have the following permission:

  • rbac.*.read_role
post/v2/permissions.listRoles

Request body

limitinteger

Maximum number of roles to return in a single response. Use smaller values for faster response times and better UI performance. Use larger values when you need to process many roles efficiently. Results exceeding this limit will be paginated with a cursor for continuation.

cursorstring

Pagination cursor from a previous response to fetch the next page of roles. Include this when you need to retrieve additional roles beyond the first page. Each response containing more results will include a cursor value that can be used here. Leave empty or omit this field to start from the beginning of the role list.

searchstring

Free-form text to filter roles. Returns roles whose ID, name, or description contains the search string. Matching is case-insensitive.

Example request

{
  "limit": 50,
  "cursor": "eyJrZXkiOiJyb2xlXzEyMzQifQ==",
  "search": "admin"
}

Response

Roles retrieved successfully

Example response

{
  "meta": {
    "requestId": "req_123"
  },
  "data": [
    {
      "id": "role_1234567890abcdef",
      "name": "support.readonly",
      "description": "Provides read-only access for customer support representatives to view user accounts and support tickets",
      "permissions": [
        {
          "id": "perm_1234567890abcdef",
          "name": "users.read",
          "slug": "users-read",
          "description": "Allows reading user profile information and account details"
        }
      ]
    }
  ],
  "pagination": {
    "cursor": "eyJrZXkiOiJrZXlfMTIzNCIsInRzIjoxNjk5Mzc4ODAwfQ==",
    "hasMore": true
  }
}

Changes

Changed in 5 of the 92 revisions of this API.6

  • 43ad1ce9a1522See the full diff
    • ○

      the endpoint scheme security bearer was added to the API

      api-security-added

    • ○

      the endpoint scheme security rootKey was removed from the API

      api-security-removed

    This revision also has 5 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • db25ebfde9a61See the full diff
    • ○

      the response property pagination became required for the status 200

      response-property-became-required

  • 0b9c06bab7071See the full diff
    • ○

      added the new optional request property search

      new-optional-request-property

  • 551df53dd45d1See the full diff
    • ○

      added the non-success response with the status 429

      response-non-success-status-added

  • 9a9c22b6dd091See the full diff
    • ○

      api operation id listRoles removed and replaced with permissions.listRoles

      api-operation-id-removed