list(options?: RoleListOptions): Promise<Page<RoleResource>>Returns a single page of roles as items plus the raw pagination envelope. The page holds the three system roles, owner, admin and viewer, alongside any custom roles the workspace has defined. These id values are what members.invite and members.update expect, so this is usually the first call in any membership flow.
The API reads the full role set and slices it in memory, so pagination.totalCount is exact rather than an estimate. System roles always sort ahead of custom roles no matter what ordering is requested. For a system row, permissions is the canonical list computed from the platform catalogue instead of whatever is stored on the record, so it always matches the current definition of that role.
Example
const page = await envless.roles.list({ limit: 50 })
for (const role of page.items) console.log(role.id, role.name, role.isSystem)Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
options.limit | number | No | Rows per page, a whole number from 1 to 100. |
options.offset | number | No | Rows to skip before the page starts. |
options.search | string | No | Case insensitive substring match against role name and description. |
options.sortBy | RoleSort | No | Order within each group: name (the default) is A to Z, updated and created are newest first. System roles always come first. |
options.signal | AbortSignal | No | Cancels the request. |
Returns
Page<RoleResource> with items and the pagination envelope.
Reads the roles collection. list returns one page as { items, pagination }, listAll collects every page into an array, and iterate streams one item at a time without buffering the whole set.
Worth knowing
- A workspace can hold at most 28 roles, three system plus 25 custom, so a single page of 100 always covers the whole set.
Required scopes
roles:read
Underlying endpoint
GET /roles
Request and response schema, every error code, and a live playground.
In Python
envless.roles.list()
The same method in envless-sdk, the Python SDK, with the same request, retries and errors.
In Ruby
Envless.roles.list
The same method in envless-sdk, the Ruby gem, with the same request, retries and errors.
In PHP
$envless->roles->list()
The same method in envless/sdk, the PHP SDK, with the same request, retries and errors.