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	Create a new role
GET	/roles	List all roles
GET	/roles/{role}	Get a specific role
PUT	/roles/{role}	Update a role
DELETE	/roles/{role}	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 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).

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	Controls what a user can do globally (e.g., send messages, create groups)
Scope (SBAC)	Within a group	Group membership	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).

Relationships

• Users — Each User has one role. Change it via the Update User API.
• Group Members — Each member in a Group has a scope (admin, moderator, or participant). Change it via the Update Group Member Scope API.
• Restrict Features — Use the Restrict Features API to limit what users with a specific role can do.
• RBAC — App-wide permissions per role. See RBAC.
• SBAC — Group-level permissions per scope. See SBAC.

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.

For all system limits (role caps, ID length, metadata, etc.), see Properties and Constraints.