Roles

Create 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.

post/role

Request

  • Base URL: https://api.elaichi.ai
  • URL: https://api.elaichi.ai/role
  • Auth: HTTP bearer

Headers

X-Organization-Idstring

Target organization (org_…). Required for cookie/session auth on org-scoped routes; optional for API tokens, which carry their organization, and rejected when it names a different one.

Request body

namestring required
descriptionstring nullable
permissionsstring[] required

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

Response

Created

idstring

Role id (role_…).

namestring
descriptionstring nullable
is_systemboolean

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

seat_class'billable' | 'free_admin'

Whether members holding only this role count toward billable seats.

permissionsstring[]

Every permission the role holds, including any GET /permission does not list for this organization (for example the Apps permissions while Apps are unavailable). PATCH /role/{id} replaces this list wholesale, so send back the entries you did not mean to remove.

permission_countinteger

How many of permissions GET /permission lists for this organization: the number to show beside the role. Can be lower than permissions.length.

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 (or, on POST /role/{id}/delete, reassign_to and/or a reassignments entry for every holder).

pending_invite_countinteger

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

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.

can_reassign_holdersboolean

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

created_atstring date-time
updated_atstring date-time

Changes

No recorded changes to this operation across all 1 revision of this API.