def delete(
id: str,
*,
timeout: float | None = None,
) -> DeletedRoleResourceasync def delete(
id: str,
*,
timeout: float | None = None,
) -> DeletedRoleResourceSoft deletes a custom role and returns 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
from envless import envless
role = envless.roles.list_all(search='deploy')[0]
removed = envless.roles.delete(role['id'])
print(removed['name'])import asyncio
from envless import AsyncEnvless
async def main() -> None:
async with AsyncEnvless() as envless:
role = (await envless.roles.list_all(search='deploy'))[0]
removed = await envless.roles.delete(role['id'])
print(removed['name'])
asyncio.run(main())Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | str | Yes | Role id from roles.list, which must be a custom role with no members and no pending invites. |
timeout | float | No | Seconds each attempt of this call may take, the response body included, before it raises EnvlessNetworkError with is_timeout set. Overrides the client's timeout for this call, and 0 turns the limit off. |
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 TypeScript
envless.roles.delete()
The same method in @goenvless/sdk, with the same request, retries and errors.