---
title: "Delete role"
method: DELETE
path: "/role/{id}"
tags: ["Roles"]
---

# Delete role

`DELETE /role/{id}`

## Request

- Base URL: `https://api.elaichi.ai`
- URL: `https://api.elaichi.ai/role/{id}`
- Auth: HTTP bearer

Deletes a custom role. Irreversible. A member holds exactly one role, so a role anybody still holds cannot simply disappear: without `reassign_to` the call answers `400 role_in_use` while `member_count` or `pending_invite_count` is above zero (`GET /member?role_id={id}` lists the holders). With `reassign_to`, every holder and every pending invite for the role is moved onto that role and the role is deleted in one atomic operation — everything moves and the role is gone, or nothing changes. The move takes effect on each member's next request. A role that a SCIM group mapping assigns (`group_mapping_count` above zero) is refused with `409 role_mapped`, `reassign_to` or not: change the mapping first. Requires `role:manage` and the `custom_roles` feature. Sending `reassign_to` at all additionally requires `member:manage` and that you hold every permission the replacement role carries (the `PATCH /member/{userId}` rules), and the target must exist and differ from `id` — checked whether or not anything needs moving. It is further refused if you hold the deleted role yourself, if the replacement is Org Owner and you are not one, or if it would leave no billable member. System roles cannot be deleted. This is the query-parameter-only form; `POST /role/{id}/delete` is the same operation with a JSON body, for a client that also wants to move specific holders onto a role of their own choosing. A browser session must also pass a fresh step-up reauthentication in the app (without it the call answers `428 step_up_required`). An organization API token is not challenged.

## Path parameters

- `id` string, required

## Query parameters

- `reassign_to` string

## Headers

- `X-Organization-Id` string

## Response `200`

OK

- object
  - `success` boolean, required
  - `reassigned_member_count` integer, required: How many members were moved onto `reassign_to`. 0 when none held the role.
  - `reassigned_invite_count` integer, required: How many pending invites were re-pointed at `reassign_to`.
  - `reassigned_by_role` object[]: One row per distinct role members were moved onto (just `reassign_to` here). Empty when nobody held the role.
    - `role_id` string
    - `role_name` string
    - `count` integer

## Other responses

- `400`: Bad request
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not found
- `429`: Rate limited

---

[API](https://skmtc.dev/elaichi/apis/elaichi-api.md) · [All operations](https://skmtc.dev/elaichi/apis/elaichi-api/llms.txt) · [OpenAPI document](https://skmtc.dev/elaichi/apis/elaichi-api/revisions/b22cfb7b6d15?raw)