Delete Role
Delete a custom role from your active account. Deleting a role also removes its permission matrix.
Two safeguards apply:
- Built-in roles cannot be deleted. The account owner is not a role at all (the owner is identified on the membership and holds every permission implicitly), so there is nothing to delete there either.
- A role that is still in use is rejected. If any active member is assigned the role, the request fails — reassign those members to another role first, then delete. The number of members on a role is visible as
member_countin List Roles.
Permission required
Requires roles:delete. The account owner always passes — the owner holds every permission implicitly.
Path parameters
uuid string (uuid) Req
The
uuid of the role to delete (from /account/roles). Must belong to your active account.Deprecated: the legacy integer id is still accepted in the path until the sunset, answered with Deprecation and Sunset headers. Use the uuid.
Response (200 OK)
success bool
true when the role was deleted.Errors
400 Bad Request
The role is in use by one or more members (reassign them first), the role is built-in, or an integer id after the sunset (
integer_id_unsupported).401 Unauthorized
Missing or invalid auth.
403 Forbidden
No active account, or your role lacks
roles:delete.404 Not Found
No role with that uuid in your active account (another account's role reads the same).
Request
curl -X DELETE "https://api.ngris.com/v1/account/roles/019a9e4e-0c47-7ca0-a55a-00a4a0094d0e" \
-H "X-API-KEY: <your_api_key>"
Python
from ngris import Ngris
client = Ngris(api_key="<your_api_key>")
client._delete_void("/account/roles/019a9e4e-0c47-7ca0-a55a-00a4a0094d0e")
Response — 200 OK
{
"success": true
}
Response — 400 (role in use)
{
"error": "role is in use by 2 member(s); reassign them first"
}
Was this helpful?