Skip to main content
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

​
Request

​
limit
integer
default:"100"
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.Min: 1Max: 100Example: 50
​
cursor
string
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.Max length: 1024 charactersExample: eyJrZXkiOiJyb2xlXzEyMzQifQ==

​
Response

​
data
array
required
Array of role objects.Each role includes:
  • id: Role identifier
  • name: Role name
  • description: Role description (if set)
  • permissions: Array of assigned permissions
  • createdAt: Creation timestamp
  • updatedAt: Last update timestamp
​
pagination
object
Pagination information for fetching additional results.
​
cursor
string
Token to fetch the next page of results.
​
hasMore
boolean
Whether more results are available.

​
Examples

curl -X POST https://api.unkey.com/v2/permissions.listRoles \
  -H "Authorization: Bearer <UNKEY_ROOT_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "limit": 50
  }'

​
With Pagination

curl -X POST https://api.unkey.com/v2/permissions.listRoles \
  -H "Authorization: Bearer <UNKEY_ROOT_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "limit": 50,
    "cursor": "eyJrZXkiOiJyb2xlXzEyMzQifQ=="
  }'

​
Response Example

{
  "meta": {
    "requestId": "req_1234abcd"
  },
  "data": [
    {
      "id": "role_123",
      "name": "admin",
      "description": "Full administrative access",
      "permissions": [
        {
          "id": "perm_123",
          "name": "admin.read"
        },
        {
          "id": "perm_124",
          "name": "admin.write"
        }
      ],
      "createdAt": 1704067200000,
      "updatedAt": 1704153600000
    },
    {
      "id": "role_124",
      "name": "editor",
      "description": "Content editing permissions",
      "permissions": [
        {
          "id": "perm_125",
          "name": "content.read"
        },
        {
          "id": "perm_126",
          "name": "content.write"
        }
      ],
      "createdAt": 1704067200000,
      "updatedAt": 1704067200000
    }
  ],
  "pagination": {
    "cursor": "eyJrZXkiOiJyb2xlXzEyNSJ9",
    "hasMore": true
  }
}

Build docs developers (and LLMs) love

Get started for freeTalk to us