Roles

$envless->roles->listPermissions()

Read the permission catalogue and system role sets

php
/** @return PermissionsResource */
public function listPermissions(int|float|null $timeout = null): array

Returns the complete catalogue of permission strings the platform understands, the same catalogue grouped by resource in byResource, and the exact permission lists behind owner, admin and viewer in systemRoles. Read it before create or update so you only ever send names that exist.

Filter on assignableToCustomRoles when you build a picker: the false entries, workspace:delete and billing:manage, are refused for every custom role regardless of who asks. The catalogue is only the outer ceiling, the caller permission check still applies on top of it, so a list that passes validation can still be rejected with 403.

This response is not a collection and takes no list options. The pagination middleware accepts limit and offset on the route, but they have no effect, which is why the SDK signature only takes a request scope.

Example

php
use Envless\Envless;

$envless = new Envless();

$catalogue = $envless->roles->listPermissions();
$assignable = array_filter(
    $catalogue['permissions'],
    static fn(array $entry): bool => $entry['assignableToCustomRoles'],
);
$owner = $catalogue['systemRoles']['owner'];

echo implode(', ', array_keys($catalogue['byResource'])), PHP_EOL;
echo count($assignable), ' assignable of ', count($owner), PHP_EOL;

Parameters

ParameterTypeRequiredDescription
$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

PermissionsResource with the flat permissions array, the byResource index and the systemRoles sets.

Worth knowing

  • The payload is static for a given API version, so fetch it once and cache it rather than calling it before every role edit.
  • byResource keys are the part of each permission string before the colon, so byResource['variables'] holds variables:read through variables:delete.
  • systemRoles['owner'] is the entire catalogue, which makes it the quickest way to see everything the platform can grant.

Required scopes

roles:read

Underlying endpoint

GET /permissions

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

In TypeScript

envless.roles.listPermissions()

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