Delete Role API

Permanently deletes a custom RBAC role from the tenant.

Use this endpoint to remove a role that is no longer needed — all users currently assigned to it must be reassigned to a different role before deletion will succeed.

About Delete Role

Deleting a custom role removes it from the tenant permanently. Any users currently assigned to this role via AuthZ Role User must be reassigned to a different role before this endpoint can be called — attempting to delete a role with active user assignments will fail. Returns HTTP 204 on success with no response body.

Key Parameters

role_id — the UUID of the role to delete; obtain from GET /authz2/v1/roles/

Common Use Cases

Removing a role that was created for a temporary project or team that no longer exists

Cleaning up duplicate or incorrectly configured roles during an access audit

Best Practices

Before deleting, call GET /user/ and cross-reference profile.authz_role_id to identify any users still assigned to this role — you must reassign or remove them before deletion will succeed

Confirm deletion success via the 204 response before removing the role from any internal documentation or automation

Workflow

Call GET /authz2/v1/roles/ to confirm the target role's role_id

Call GET /user/ and cross-reference profile.authz_role_id to identify all users assigned to this role

Call PUT /authz2/v1/users/{user_id} for each assigned user to reassign them to a different role

Call DELETE /authz2/v1/roles/{role_id} once no users remain assigned to the role

Confirm the 204 response indicating successful deletion