delete(id: string, options?: RequestScope): Promise<DeletedRoleResource>Soft deletes a custom role and resolves with a small receipt holding the id and name that were removed. The id is never reused, and the role reads as 404 from then on.
The role has to be unused. Reassign every member holding it with members.update and revoke every pending invite that references it with invites.revoke first, otherwise the call is refused with 409 role.in_use and the message tells you how many members or invites are in the way. System roles can never be deleted and fail with 409 role.immutable.
Example
const [role] = await envless.roles.listAll({ search: 'deploy' })
const removed = await envless.roles.delete(role.id)
console.log(removed.name)Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Role id from roles.list, which must be a custom role with no members and no pending invites. |
options.signal | AbortSignal | No | Cancels the request. |
Returns
DeletedRoleResource carrying only the id and name of the removed role.
Worth knowing
- The response omits
permissions,descriptionand the timestamps, so read anything you want to keep withgetbefore deleting. - Members are counted before invites, so a role blocked by both reports the member count first and the invite count only after you clear the members.
- Deleting a role emits the
role.deletedwebhook event.
Required scopes
roles:write
Underlying endpoint
DELETE /roles/{id}
Request and response schema, every error code, and a live playground.
In Python
envless.roles.delete()
The same method in envless-sdk, the Python SDK, with the same request, retries and errors.
In Ruby
Envless.roles.delete
The same method in envless-sdk, the Ruby gem, with the same request, retries and errors.
In PHP
$envless->roles->delete()
The same method in envless/sdk, the PHP SDK, with the same request, retries and errors.