Roles

envless.roles.update()

Change a custom role name, description or permissions

ts
update(id: string, patch: RolePatch, options?: RequestScope): Promise<RoleResource>

Patches a custom role. Every field is optional, but patch.permissions is a full replacement rather than a merge: send the complete list the role should end up with, or leave the key out entirely to keep the current one. Passing description: null clears the description.

System roles are immutable. Patching owner, admin or viewer fails with 409 role.immutable however harmless the field, so gate the call on isSystem. The same two ceilings as creation apply to the permission list: the never assignable permissions fail validation with 400 request.body_invalid, and anything the key owner does not hold themselves fails with 403 auth.permission_denied.

A permission change is live immediately for every member holding the role. Existing API keys owned by those members are not re-clamped by this call, only by a change to the member role, so a key can keep a scope its owner no longer has until that key is updated.

Example

ts
const [role] = await envless.roles.listAll({ search: 'deploy' })

const updated = await envless.roles.update(role.id, {
    description: null,
    permissions: ['projects:read', 'environments:read', 'variables:read']
})

console.log(updated.permissions)

Parameters

ParameterTypeRequiredDescription
idstringYesRole id from roles.list, which must belong to a custom role.
patch.namestringNoNew display name, still subject to case insensitive uniqueness.
patch.descriptionstring | nullNoNew description, or null to clear the existing one.
patch.permissionsArray<string>NoComplete replacement permission list, not a set of additions.
options.signalAbortSignalNoCancels the request.

Returns

RoleResource reflecting the stored role after the patch.

Worth knowing

  • Sending permissions: [] strips every permission from the role, which is very different from omitting the key.
  • Read the role back with get before patching if you intend to add one permission, since you have to resend the ones you want to keep.
  • A successful patch emits the role.updated webhook event.

Required scopes

roles:write

Underlying endpoint

PATCH /roles/{id}

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

In Python

envless.roles.update()

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

In Ruby

Envless.roles.update

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

In PHP

$envless->roles->update()

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