Roles

Get role

Returns one role with its permissions and member counts. Any member may read it.

get/role/{id}

Request

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

Path parameters

idstring required

Role id (role_…).

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.

Response

OK

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.