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

Request

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

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

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

object

Pagination information for fetching additional results.

string

Token to fetch the next page of results.

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
  }'

import { Unkey } from "@unkey/api";

const unkey = new Unkey({ token: process.env.UNKEY_ROOT_KEY });

const result = await unkey.permissions.listRoles({
  limit: 50,
});

console.log(result.result);

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=="
  }'

import { Unkey } from "@unkey/api";

const unkey = new Unkey({ token: process.env.UNKEY_ROOT_KEY });

const result = await unkey.permissions.listRoles({
  limit: 50,
  cursor: "eyJrZXkiOiJyb2xlXzEyMzQifQ==",
});

console.log(result.result);

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
  }
}

Overview

Keys

APIs

Rate Limiting

Identities

Analytics

Permissions

Required Permissions

Request

Response

Examples

Response Example

​Required Permissions

​Request

​Response

​Examples

​With Pagination

​Response Example

Required Permissions

Request

Response

Examples

With Pagination

Response Example