Roles

Update role

Updates a custom role. permissions is REPLACED wholesale, not merged — the array you send becomes the role's entire permission set, so anything omitted is revoked from every member holding the role. Read the role first and send the full intended list. Omitting permissions entirely leaves it untouched. Edits apply immediately: effective permissions are recomputed on every request. Requires role:manage, the custom_roles feature, and that you hold every permission you are granting.

patch/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.

Request body

namestring
descriptionstring nullable
permissionsstring[]

Replaces the role's permission set entirely.

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.