> ## Documentation Index
> Fetch the complete documentation index at: https://exsited.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Roles

> List, read, create, update, enable, disable and delete the user roles on an Exsited instance.

Roles are the settings records for user roles, and each says whether it is a system role. You can list, read, create, update, enable or disable and delete roles. This area has 5 endpoints, and all seven SDKs call every one.

## At a glance

| Endpoint | Method | Path | What it does |
| - | - | - | - |
| [List roles](https://exsited.mintlify.site/api-reference/roles/list-roles.md) | GET | `/settings/roles` | Returns a page of roles under `data`, with paging details under `pagination`. |
| [Create a role](https://exsited.mintlify.site/api-reference/roles/create-a-role.md) | POST | `/settings/roles` | Creates a role and returns it under `role`. |
| [Retrieve a role](https://exsited.mintlify.site/api-reference/roles/retrieve-a-role.md) | GET | `/settings/roles/{role_id}` | Returns one role by its `id`, under `role`. |
| [Delete a role](https://exsited.mintlify.site/api-reference/roles/delete-a-role.md) | DELETE | `/settings/roles/{role_id}` | Deletes a role. A system role is refused. |
| [Update a role](https://exsited.mintlify.site/api-reference/roles/update-a-role.md) | PATCH | `/settings/roles/{role_id}` | Changes a role, or enables or disables it. |

## Before you call

Register your API credentials once when your app starts, as shown in
[Authentication](https://exsited.mintlify.site/authentication.md). Every SDK sample on these pages then gets its client in one line.
With cURL, send the access token in an `Authorization` header: `Authorization: Bearer $ACCESS_TOKEN`.

## Things to know

* **Responses wrap a role in `role`.** A single read returns `{"role": {...}}`.
* **`is_system_role` marks the built-in roles.** A delete of a system role is refused.
* **Listings page by cursor.** Records sit under `data`; pass `pagination.next_cursor` as `cursor` to read the next page, and stop when `pagination.has_more` is `false`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.