Retrieve all roles in your workspace including their assigned permissions. Results are paginated and sorted by their id.
Use this to audit your access control setup, verify role-permission mappings, or build automation that reacts to your current RBAC configuration.
Required permissions:
rbac.*.read_role
See the API reference for the full HTTP endpoint documentation.
Usage#
Flags#
Maximum number of roles to return in a single response (1-100, default 100). 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.
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 flag to start from the beginning of the role list.
Free-form text to filter roles. Returns roles whose ID, name, or description contains the search string. Matching is case-insensitive.
Global Flags#
| Flag | Type | Description |
|---|---|---|
--root-key | string | Override root key ($UNKEY_ROOT_KEY) |
--api-url | string | Override API base URL (default: https://api.unkey.com) |
--config | string | Path to config file (default: ~/.unkey/config.toml) |
--output | string | Output format. Use json for raw JSON |
--body | string | Send this JSON string as the request body. You cannot combine it with request-building flags. |
Examples#
Output#
Default output shows the request ID, followed by the list of roles and their permissions:
With --output=json, the full response envelope is returned including pagination metadata: