> ## Documentation Index
> Fetch the complete documentation index at: https://cometchat-22654f5b-docs-llms-scoped-indexes.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Define and manage CometChat user roles with REST APIs to control permissions and feature access across your 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).


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