Skip to main content
Retrieve all permissions in your workspace. Results are paginated and sorted by their id.

​
Required Permissions

Your root key must have the following permission:
  • rbac.*.read_permission

​
Request

​
limit
integer
default:"100"
Maximum number of permissions to return in a single response.Min: 1Max: 100Example: 50
​
cursor
string
Pagination cursor from a previous response to fetch the next page of permissions.Include this value when you need to retrieve additional permissions beyond the initial response.Each response containing more results than the requested limit includes a cursor for subsequent pages.Leave empty or omit this field to start from the beginning of the permission list.Cursors are temporary and may expire - always handle cases where a cursor becomes invalid.Max length: 1024 charactersExample: eyJrZXkiOiJwZXJtXzEyMzQifQ==

​
Response

​
data
array
required
Array of permission objects.Each permission includes:
  • id: Permission identifier
  • name: Permission name
  • slug: URL-safe identifier
  • description: Permission description (if set)
  • 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.listPermissions \
  -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.listPermissions \
  -H "Authorization: Bearer <UNKEY_ROOT_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "limit": 50,
    "cursor": "eyJrZXkiOiJwZXJtXzEyMzQifQ=="
  }'

​
Response Example

{
  "meta": {
    "requestId": "req_1234abcd"
  },
  "data": [
    {
      "id": "perm_123",
      "name": "documents.read",
      "slug": "documents-read",
      "description": "Allows reading document resources",
      "createdAt": 1704067200000,
      "updatedAt": 1704067200000
    },
    {
      "id": "perm_124",
      "name": "documents.write",
      "slug": "documents-write",
      "description": "Allows writing document resources",
      "createdAt": 1704067200000,
      "updatedAt": 1704067200000
    },
    {
      "id": "perm_125",
      "name": "users.read",
      "slug": "users-read",
      "description": "Allows reading user information",
      "createdAt": 1704067200000,
      "updatedAt": 1704067200000
    }
  ],
  "pagination": {
    "cursor": "eyJrZXkiOiJwZXJtXzEyNiJ9",
    "hasMore": true
  }
}

Build docs developers (and LLMs) love

Get started for freeTalk to us