<!-- https://headless-lms.dev/docs/api/roles -->

# Roles

The organization's roles and their permissions

- [The organization's roles](https://headless-lms.dev/docs/api/roles/listRoles): Requires `roles:read`. Each role with its levels, permissions and the number of people who hold it.
- [Add a role](https://headless-lms.dev/docs/api/roles/createRole): Requires `roles:write`. The role starts from a deployment role (`base`) and needs every permission it holds.
- [Read a role](https://headless-lms.dev/docs/api/roles/getRole): Requires `roles:read`.
- [Rename or change a role](https://headless-lms.dev/docs/api/roles/updateRole): Requires `roles:write`. A rename needs nothing else. Changing permissions, levels or the team flag needs every permission the role holds before and after the change (403 names the missing ones). Owner and Member can only be renamed (409). Names are unique in the organization (409).
- [Delete a role the organization added](https://headless-lms.dev/docs/api/roles/deleteRole): Requires `roles:delete`. Refused while anyone holds it (409, with the count).
- [Reset a role to the deployment's version](https://headless-lms.dev/docs/api/roles/resetRole): Requires `roles:write`. Needs every permission the role holds before and after.
