UNunkeyed
permissions

List roles

Changed on

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

  • Base URL
    https://api.unkey.com
  • URL
    https://api.unkey.com/v2/permissions.listRoles
  • Auth
    HTTP bearer

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