Skip to main content
Retrieve all permissions in your workspace. Results are paginated and sorted by their id. Use the --limit and --cursor flags to traverse large permission sets efficiently. Required permissions:
  • rbac.*.read_permission
See the API reference for the full HTTP endpoint documentation.

​
Usage

unkey api permissions list-permissions [flags]

​
Flags

​
--limit
integer
Maximum number of permissions to return in a single response. Accepts a value between 1 and 100. Defaults to 100 when omitted.
​
--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. Leave empty or omit this flag to start from the beginning of the permission list. Cursors are temporary and may expire — always handle cases where a cursor becomes invalid.

​
Global Flags

FlagTypeDescription
--root-keystringOverride root key ($UNKEY_ROOT_KEY)
--api-urlstringOverride API base URL (default: https://api.unkey.com)
--configstringPath to config file (default: ~/.unkey/config.toml)
--outputstringOutput format — use json for raw JSON

​
Examples

unkey api permissions list-permissions

​
Output

Default output shows the request ID with latency, followed by the list of permissions: 
req_2c9a0jf23l4k567 (took 32ms)

[
  {
    "id": "perm_1234567890abcdef",
    "name": "users.read",
    "slug": "users-read",
    "description": "Allows reading user profile information and account details"
  }
]
With --output=json, the full response envelope including pagination metadata is returned: 
{
  "meta": {
    "requestId": "req_2c9a0jf23l4k567"
  },
  "data": [
    {
      "id": "perm_1234567890abcdef",
      "name": "users.read",
      "slug": "users-read",
      "description": "Allows reading user profile information and account details"
    }
  ],
  "pagination": {
    "hasMore": true,
    "cursor": "eyJrZXkiOiJwZXJtXzEyMzQiLCJ0cyI6MTY5OTM3ODgwMH0="
  }
}
Last modified on March 26, 2026