Delete role

DELETE /role/{id}

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. A BROWSER SESSION must additionally carry a fresh step-up reauthentication (`X-Step-Up-Token`, obtained from `/auth/step-up`); without one the call answers `428 step_up_required` and `error.details` names the action and resource to prove. An organization API token is not challenged: step-up re-proves the person behind a session, and a token has no person behind it.

Path Parameters

idstring

required·

Role id (role_…).

Query Parameters

reassign_tostring

Role id (role_…) to move every current holder and pending invite onto before deleting. Must exist and differ from id; its authorization (member:manage and the grant ceiling) applies even when nothing holds the role, in which case nothing is moved.

Response Body

reassigned_invite_countinteger

How many pending invites were re-pointed at reassign_to.

reassigned_member_countinteger

How many members were moved onto reassign_to. 0 when none held the role.

successboolean

curl -X DELETE 'https://api.elaichi.ai/role/<id>' \
  -H 'Authorization: Bearer $ELAICHI_API_TOKEN' \
  -H 'Content-Type: application/json'

const response = await fetch('https://api.elaichi.ai/role/<id>', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer ' + process.env.ELAICHI_API_TOKEN,
    'Content-Type': 'application/json',
  },
});

const data = await response.json();
console.log(data);

import os
import requests

url = "https://api.elaichi.ai/role/<id>"
headers = {
    "Authorization": f"Bearer {os.environ['ELAICHI_API_TOKEN']}",
    "Content-Type": "application/json",
}

response = requests.delete(url, headers=headers)
print(response.json())