Create role

POST /role

Authoring custom roles requires the `role:manage` permission and the `custom_roles` plan feature; the predefined system roles stay readable and assignable on every plan. You may only grant permissions you hold yourself — otherwise an admin could mint a role carrying `billing:manage` and assign it to themselves. Validate names against `GET /permission`.

Request Body

descriptionstring,null

namestring

permissionsstring[]

Permission names from GET /permission. The complete set for this role.

Response Body

can_reassign_holdersboolean

Whether you may move this role's holders and pending invites to another role (DELETE /role/{id}?reassign_to=): you hold member:manage and do not hold this role yourself.

created_atstring · date-time

descriptionstring,null

group_mapping_countinteger

SCIM group mappings that assign this role. Present only on roles you can manage. While above zero, DELETE /role/{id} is refused (409 role_mapped) until the mappings change.

idstring

Role id (role_…).

is_systemboolean

Predefined roles ship with every organization and cannot be edited away.

member_countinteger

How many members hold this role right now. GET /member?role_id={id} lists them; while it is above zero, DELETE /role/{id} needs reassign_to.

namestring

pending_invite_countinteger

Pending invites issued for this role. Present only on roles you can manage. While above zero, DELETE /role/{id} needs reassign_to, which re-points them.

permissionsstring[]

Permission names from GET /permission. PATCH /role/{id} replaces this list wholesale.

seat_classstring

Whether members holding only this role count toward billable seats.

Possible values:

billablefree_admin

updated_atstring · date-time

curl -X POST 'https://api.elaichi.ai/role' \
  -H 'Authorization: Bearer $ELAICHI_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"name":"your_name","permissions":[]}'

const body = {
  "name": "your_name",
  "permissions": []
};

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

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

import os
import requests

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

response = requests.post(url, headers=headers, json=payload)
print(response.json())