Roles

$envless->roles->list()

Read one page of workspace roles

php
/** @return Page<RoleResource> */
public function list(
    ?int $limit = null,
    ?int $offset = null,
    ?string $search = null,
    ?string $sortBy = null,
    int|float|null $timeout = null,
): Page

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 $envless->members->invite() and $envless->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

php
use Envless\Envless;

$envless = new Envless();

$page = $envless->roles->list(limit: 50);

foreach ($page->items as $role) {
    $system = $role['isSystem'] ? ' (system)' : '';

    echo $role['id'], ' ', $role['name'], $system, PHP_EOL;
}

Parameters

ParameterTypeRequiredDescription
$limitintNoRows per page, a whole number from 1 to 100.
$offsetintNoRows to skip before the page starts.
$searchstringNoCase insensitive substring match against role name and description.
$sortBystringNoOrder within each group: name (the default) is A to Z, updated and created are newest first. System roles always come first.
$timeoutint|floatNoSeconds each attempt of this call may take, the response body included, before it throws Envless\Exception\NetworkException with isTimeout() true. 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 an Envless\Result\Page with items and pagination, listAll collects every page into an array, and iterate returns a Generator that yields one item at a time, fetching the next page only when the loop gets there.

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.