Roles

$envless->roles->get()

Fetch one role by id

php
/** @return RoleResource */
public function get(string $id, int|float|null $timeout = null): array

Reads a single role. Unlike products and projects, there is no slug form here: the argument must be the role id taken from list, and a role name or a system key such as owner comes back as 404 role.not_found.

For a system role, permissions is the canonical catalogue list for its systemKey rather than the stored column, so it stays correct as the platform permission set grows. systemKey is null for custom roles, and isSystem is the flag to branch on before offering an edit or delete action, since both are refused on system roles.

Example

php
use Envless\Envless;

$envless = new Envless();

$role = $envless->roles->listAll(search: 'deploy')[0] ?? null;

if ($role !== null) {
    $detail = $envless->roles->get($role['id']);

    echo implode(', ', $detail['permissions']), PHP_EOL;
}

Parameters

ParameterTypeRequiredDescription
$idstringYesRole id from $envless->roles->list(), with no name or slug form accepted.
$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

RoleResource with permissions, isSystem, systemKey and timestamps.

Worth knowing

  • A soft deleted role is indistinguishable from one that never existed: both answer 404 role.not_found.
  • The role must belong to the workspace the API key is bound to, since ids from another workspace also read as 404.

Required scopes

roles:read

Underlying endpoint

GET /roles/{id}

Request and response schema, every error code, and a live playground.

In TypeScript

envless.roles.get()

The same method in @goenvless/sdk, with the same request, retries and errors.