def list(
*,
limit: int | None = None,
offset: int | None = None,
search: str | None = None,
sort_by: str | None = None,
timeout: float | None = None,
) -> Page[RoleResource]async def list(
*,
limit: int | None = None,
offset: int | None = None,
search: str | None = None,
sort_by: str | None = None,
timeout: float | None = None,
) -> 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
from envless import envless
page = envless.roles.list(limit=50)
for role in page['items']:
print(role['id'], role['name'], role['isSystem'])import asyncio
from envless import AsyncEnvless
async def main() -> None:
async with AsyncEnvless() as envless:
page = await envless.roles.list(limit=50)
for role in page['items']:
print(role['id'], role['name'], role['isSystem'])
asyncio.run(main())Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
limit | int | No | Rows per page, a whole number from 1 to 100. |
offset | int | No | Rows to skip before the page starts. |
search | str | No | Case insensitive substring match against role name and description. |
sort_by | str | No | Order within each group: name (the default) is A to Z, updated and created are newest first. System roles always come first. |
timeout | float | No | Seconds each attempt of this call may take, the response body included, before it raises EnvlessNetworkError with is_timeout set. Overrides the client's timeout for this call, and 0 turns the limit off. |
Returns
Page[RoleResource] with items and the pagination envelope.
Reads the roles collection. list returns one page as a dict with items and pagination, list_all collects every page into a list, and iterate yields one item at a time, fetching the next page only when the loop reaches it. On AsyncEnvless, iterate is an async iterator for async for.
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 TypeScript
envless.roles.list()
The same method in @goenvless/sdk, with the same request, retries and errors.