Added
Roles API
September 30th, 2026
Roles are now available through the public API. A role is a named set of permissions that applies inside a structure, and it grants nothing until you assign users to it.
The following APIs enable you to create, read, and replace roles, plus assign users to them and read who holds them:
| Endpoint name | Endpoint |
|---|---|
| Create a role | POST /permissions/v1/roles |
| Get a role | GET /permissions/v1/roles/{role_id} |
| Update a role | PUT /permissions/v1/roles/{role.id} |
| Add users to a role | POST /structures/v1/roles/{role_id}/members |
| List users by role | POST /structures/v1/roles/{role_id}/members/list |
Developer impact: There is no endpoint to list roles, so track the id returned by POST /permissions/v1/roles. Managing a role created outside the API, such as one created in the web app, is not currently supported. PUT /permissions/v1/roles/{role.id} is a full replacement, so send the complete role on every update, including the permissions you want to keep.
Action required: No action required. Existing endpoints are unchanged.