Roles

envless.roles.listPermissions()

Read the permission catalogue and system role sets

ts
listPermissions(options?: RequestScope): Promise<PermissionsResource>

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

ts
const catalogue = await envless.roles.listPermissions()

const assignable = catalogue.permissions.filter((permission) => permission.assignableToCustomRoles)

console.log(Object.keys(catalogue.byResource))
console.log(assignable.length, catalogue.systemRoles.owner.length)

Parameters

ParameterTypeRequiredDescription
options.signalAbortSignalNoCancels the request.

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 Python

envless.roles.list_permissions()

The same method in envless-sdk, the Python SDK, with the same request, retries and errors.

In Ruby

Envless.roles.list_permissions

The same method in envless-sdk, the Ruby gem, with the same request, retries and errors.

In PHP

$envless->roles->listPermissions()

The same method in envless/sdk, the PHP SDK, with the same request, retries and errors.