> ## Documentation Index
> Fetch the complete documentation index at: https://www.cometchat.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Define and manage user roles to control permissions across your CometChat app.

A **Role** defines a set of permissions that control what a user can do in your CometChat app. Every user is assigned exactly one role — if no role is specified during user creation, the `default` role is applied automatically.

### Endpoints

| Method | Endpoint                                  | Description         |
| ------ | ----------------------------------------- | ------------------- |
| POST   | [`/roles`](/rest-api/roles/create)        | Create a new role   |
| GET    | [`/roles`](/rest-api/roles/list)          | List all roles      |
| GET    | [`/roles/{role}`](/rest-api/roles/get)    | Get a specific role |
| PUT    | [`/roles/{role}`](/rest-api/roles/update) | Update a role       |
| DELETE | [`/roles/{role}`](/rest-api/roles/delete) | Delete a role       |

### How roles work

* Roles are app-wide — they apply to a user across all groups and conversations.
* You can [restrict specific features](/rest-api/restrict-features) per role (e.g., prevent certain roles from sending attachments or creating groups).
* For fine-grained, role-based permission control, see [RBAC (Role-Based Access Control)](/rest-api/rbac-overview#rbac-role-based-access-control).

### Roles vs. Group Member Scopes

CometChat uses two layers of access control:

| Layer        | Applies to     | Assigned via                                | Purpose                                                                   |
| ------------ | -------------- | ------------------------------------------- | ------------------------------------------------------------------------- |
| Role (RBAC)  | App-wide       | [User creation/update](/rest-api/users)     | Controls what a user can do globally (e.g., send messages, create groups) |
| Scope (SBAC) | Within a group | [Group membership](/rest-api/group-members) | Controls what a member can do inside a specific group                     |

When a user joins a group, they are assigned one of three scopes:

| Scope         | Default assignment   | Privileges                                                                                           |
| ------------- | -------------------- | ---------------------------------------------------------------------------------------------------- |
| `admin`       | Group creator        | Change member scopes, add/kick/ban members, update/delete group, send & receive messages & calls     |
| `moderator`   | Promoted by an admin | Change scope of participants, kick & ban participants, update group, send & receive messages & calls |
| `participant` | All other members    | Send & receive messages & calls                                                                      |

For group operations, both RBAC and SBAC permissions must allow the action. A user's role is checked first (app-wide), then their group scope is checked (group-level). If either denies the action, the API returns `ERR_PERMISSION_DENIED`.

For the full list of scope-based permissions, see [SBAC (Scope-Based Access Control)](/rest-api/rbac-overview#sbac-scope-based-access-control).

### Relationships

* **Users** — Each [User](/rest-api/users) has one role. Change it via the [Update User API](/rest-api/users/update).
* **Group Members** — Each member in a [Group](/rest-api/groups) has a scope (`admin`, `moderator`, or `participant`). Change it via the [Update Group Member Scope API](/rest-api/group-members/change-scope).
* **Restrict Features** — Use the [Restrict Features API](/rest-api/restrict-features) to limit what users with a specific role can do.
* **RBAC** — App-wide permissions per role. See [RBAC](/rest-api/rbac-overview#rbac-role-based-access-control).
* **SBAC** — Group-level permissions per scope. See [SBAC](/rest-api/rbac-overview#sbac-scope-based-access-control).

### Role properties

| Property        | Type    | Description                                            |
| --------------- | ------- | ------------------------------------------------------ |
| **role**        | string  | Unique identifier for the role.                        |
| **name**        | string  | Human-readable display name.                           |
| **description** | string  | Description of what this role is for.                  |
| **metadata**    | object  | JSON object for storing additional role configuration. |
| **createdAt**   | integer | UNIX timestamp of when the role was created.           |

### Error handling

| Error Code                | Description                          |
| ------------------------- | ------------------------------------ |
| `ERR_ROLE_NOT_FOUND`      | The specified role does not exist    |
| `ERR_ROLE_ALREADY_EXISTS` | A role with this name already exists |

For the complete list of error codes, see [Error Guide](/articles/error-guide).

For all system limits (role caps, ID length, metadata, etc.), see [Properties and Constraints](/articles/properties-and-constraints).