def list(limit: nil, offset: nil, search: nil, sort_by: nil, timeout: nil)def list: (
?limit: Integer?,
?offset: Integer?,
?search: (String | Symbol)?,
?sort_by: ("updated" | "created" | "name")?,
?timeout: seconds?
) -> Page[role_resource]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
require "envless/sdk"
page = Envless.roles.list(limit: 50)
page.items.each do |role|
puts "#{role[:id]} #{role[:name]} #{role[:isSystem]}"
endParameters
| Parameter | Type | Required | Description |
|---|---|---|---|
limit: | Integer | No | Rows per page, a whole number from 1 to 100. |
offset: | Integer | No | Rows to skip before the page starts. |
search: | String | Symbol | No | Case insensitive substring match against role name and description. |
sort_by: | "updated" | "created" | "name" | No | Order within each group: name (the default) is A to Z, updated and created are newest first. System roles always come first. |
timeout: | Integer | Float | Rational | No | Seconds each attempt of this call may take, redirects and the response body included, before it raises Envless::NetworkError with timeout? set. Overrides the client's timeout for this call, and 0 turns the limit off. |
Returns
Page[role_resource] with items and the pagination envelope.
Reads the roles collection. list returns one page as an Envless::Page with items and pagination, list_all collects every page into an array, and iterate yields one item at a time to a block, fetching the next page only when it gets there. Without a block, iterate returns an Enumerator.
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.