---
title: "Delete Role API"
method: DELETE
path: "/authz2/v1/roles/{role_id}"
tags: ["esper_cloud_api_Roles"]
---

# Delete Role API

`DELETE /authz2/v1/roles/{role_id}`

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

## Path parameters

- `role_id` string, uuid, required

## Response `204`

Deleted succesfully

## Other responses

- `400` — Bad request
- `401` — Unauthorized request

---

[API](https://skmtc.net/esper/apis/esper-api-reference.md) · [All operations](https://skmtc.net/esper/apis/esper-api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/esper/esper-api-reference/versions/e1f64cbb488e/schema)