Roles

envless.roles.create()

Create a custom role with an explicit permission list

ts
create(body: RoleCreate, options?: RequestScope): Promise<RoleResource>

Creates a custom role from a full permission list. Take the strings from listPermissions, because anything outside that catalogue is rejected with 400 request.body_invalid.

Two separate ceilings apply to body.permissions. Permissions flagged assignableToCustomRoles: false, today workspace:delete and billing:manage, can never be held by a custom role and fail validation for everyone. Beyond that you can only grant what you already hold: the request is checked against the effective permissions of the user who owns the API key, and anything past that fails with 403 auth.permission_denied naming the offending strings in message. An admin therefore cannot mint a role stronger than admin.

Names are trimmed and must be unique within the workspace case insensitively, so Deploy bot collides with deploy bot and returns 409 role.name_conflict. A workspace holds at most 25 custom roles, and the cap is checked before the name, so a full workspace fails with 409 role.limit_reached even when the name was also taken.

Example

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

const role = await envless.roles.create({
    name: 'Deploy bot',
    description: 'Read only access for CI',
    permissions: [...catalogue.byResource.variables, ...catalogue.byResource.versions].filter((name) => name.endsWith(':read'))
})

console.log(role.id, role.permissions)

Parameters

ParameterTypeRequiredDescription
body.namestringYesDisplay name for the role, trimmed and unique within the workspace.
body.permissionsArray<string>YesComplete list of permission strings from the catalogue, with no merge or inheritance applied.
body.descriptionstring | nullNoOptional free text shown next to the role.
options.signalAbortSignalNoCancels the request.

Returns

RoleResource for the new role, with isSystem false and systemKey null.

Worth knowing

  • System roles do not count against the 25 role cap, only custom ones do.
  • Creating a role emits the role.created webhook event with the permission list in the payload.
  • Use catalogue.systemRoles.admin as a template when you want a slightly reduced admin, then remove what the role should not have.

Required scopes

roles:write

Underlying endpoint

POST /roles

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

In Python

envless.roles.create()

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

In Ruby

Envless.roles.create

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

In PHP

$envless->roles->create()

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