Overview

Configure role-based (RBAC) and scope-based (SBAC) access control permissions for your CometChat app.

Endpoints

Method	Endpoint	Description
GET	/roles/{role}/permissions	List all RBAC permissions for a role
PUT	/roles/{role}/permissions	Set RBAC permissions for a role
DELETE	/roles/{role}/permissions/{permission}	Unset a specific RBAC permission for a role
GET	/groups/{guid}/scopes/{scope}/permissions	List all SBAC permissions for a group scope
PUT	/groups/{guid}/scopes/{scope}/permissions	Set SBAC permissions for a group scope
DELETE	/groups/{guid}/scopes/{scope}/permissions/{permission}	Unset a specific SBAC permission for a group scope

CometChat provides two types of access control permissions:

• RBAC (Role-Based Access Control) Permissions applied globally based on the user’s assigned role
• SBAC (Scope-Based Access Control) Permissions applied within group context based on the member’s scope

Each type is documented independently below with its own working mechanism, data types, and permission tables.

---

RBAC (Role-Based Access Control)

Role-Based Access Control (RBAC) enables fine-grained control over what actions a user can perform and what data they can access, based on the role assigned to them (for example: doctor, patient, buyer, seller).

How RBAC Works

• Permissions are configured per role
• Each permission has a default value
• Explicitly configured permissions override defaults
• RBAC permissions are evaluated at runtime for every API request
• If a permission evaluation fails, the API returns an ERR_PERMISSION_DENIED error

RBAC supports:

• Binary permissions (allow / deny)
• Conditional permissions using additional configuration keys such as mode, allowedRoles, and allowedMessageTypes

Permissions can be restricted by additional conditions such as:

• User relationships (all users vs friends)
• Sender or receiver roles
• Message categories and types

RBAC Data Types

Data Type	Description	Example Values
string	Single string value	allow, deny, all, friends
stringArray	Array of predefined strings	["user", "group"], ["text", "image"]
rolesStringArray	Array of role names	["doctor", "patient"]
customStringArray	Array of custom user-defined strings	["custom-type-1", "custom-type-2"]

RBAC Permission Structure

Each RBAC permission follows this structure:

Attribute	Description
Key	The RBAC permission key used in APIs
Category	Logical grouping (Users, Messages, etc.)
Data Type	Expected value type
Available Values	Supported values
Default	Applied if not explicitly configured

RBAC Permission Value Behavior

When an array permission (e.g., allowedRoles, mimeTypes) has a value of null:

• It means no restriction - all values are allowed
• This is equivalent to an empty array []

For allow / deny values:

• allow: The action is permitted
• deny: The action is blocked, returns ERR_PERMISSION_DENIED

For mode values:

• all: Action applies to all users
• friends: Action is restricted to friends only

RBAC Permissions

1. Users

Title	Description	Data Type	Permission Key	Available Values	Default
User Listing	Allow or deny user listing functionality	string	listUsers	allow, deny	allow
User Listing Mode	Choose who can be listed: all users or friends only	string	listUsers.mode	all, friends	all
User Listing Role Filter	Select which user roles can be listed	rolesStringArray	listUsers.allowedRoles	null	null
User Details Access	Allow or deny viewing detailed user information	string	getUserDetails	allow, deny	allow
User Details Mode	Choose whose details can be viewed: all users or friends only	string	getUserDetails.mode	all, friends	all
User Details Role Filter	Select which user roles’ details can be viewed	rolesStringArray	getUserDetails.allowedRoles	null	null
Block User	Allow or deny user blocking functionality	string	blockUser	allow, deny	allow
Block User Role Filter	Select which user roles can be blocked	rolesStringArray	blockUser.allowedRoles	null	null
Blocked User Listing	Allow or deny listing blocked users	string	listBlockedUser	allow, deny	allow
Blocked User Listing Role Filter	Select which blocked user roles can be listed	rolesStringArray	listBlockedUser.allowedRoles	null	null
Unblock User	Allow or deny user unblocking functionality	string	unblockedUser	allow, deny	allow
Unblock User Role Filter	Select which user roles can be unblocked	rolesStringArray	unblockedUser.allowedRoles	null	null
Edit User Profile	Allow or deny user detail edits	string	editProfile	allow, deny	allow

2. Messages

Title	Description	Data Type	Permission Key	Available Values	Default
Message Listing	Allow or deny message listing functionality	string	listMessages	allow, deny	allow
Message Listing Mode	Choose whose messages can be listed: all users or friends only	string	listMessages.mode	all, friends	all
Message List Receiver Filter	Select which receiver types are allowed in message lists	stringArray	listMessages.allowedReceiverTypes	user, group	null
Message List Sender Filter	Select which sender roles’ messages can be listed	rolesStringArray	listMessages.allowedSenderRoles	null	null
Message List Category Filter	Select which message categories can be listed	stringArray	listMessages.allowedMessageCategories	message, custom	null
Message List Type Filter	Select which message types can be listed	stringArray	listMessages.allowedMessageTypes	text, image, audio, video, file	null
Message Details	Allow or deny fetching message details	string	getMessageDetails	allow, deny	allow
Message Details Mode	Choose whose message details can be viewed: all users or friends only	string	getMessageDetails.mode	all, friends	all
Message Sending	Allow or deny message sending functionality	string	sendMessage	allow, deny	allow
Message Sending Mode	Choose who can receive messages: all users or friends only	string	sendMessage.mode	all, friends	all
Message Send Receiver Filter	Select receiver types to which the messages can be sent	stringArray	sendMessage.allowedReceiverTypes	user, group	null
Message Send Role Filter	Select receiver roles to which the messages can be sent	rolesStringArray	sendMessage.allowedReceiverRoles	null	null
Message Send Category Filter	Select which message categories can be sent	stringArray	sendMessage.allowedMessageCategories	message, custom	null
Message Send Type Filter	Select which message types can be sent	stringArray	sendMessage.allowedMessageTypes	text, image, audio, video, file	null
Custom Message Types	Define custom message types that can be sent	customStringArray	sendMessage.allowedCustomTypes	null	null
MIME Type Access Control	Set MIME type filtering mode to allow or deny	string	sendMessage.mimeTypeAccessControl	allow, deny	allow
Media MIME Types	Define MIME types for media message filtering	customStringArray	sendMessage.mimeTypes	null	null
Message Editing	Allow or deny editing of own messages	string	editMessage	allow, deny	allow
Message Deletion	Allow or deny deletion of own messages	string	deleteMessage	allow, deny	allow

3. Message Thread

Title	Description	Data Type	Permission Key	Available Values	Default
Threaded Message Listing	Allow or deny listing of threaded messages	string	listThreadedMessages	allow, deny	allow
Thread Message Sending	Allow or deny sending messages in threads	string	sendThreadedMessage	allow, deny	allow
Thread Receiver Type Filter	Select which receiver types (user/group) can receive thread messages	stringArray	sendThreadedMessage.allowedReceiverTypes	user, group	null
Thread Role Filter	Select which receiver roles can receive thread messages (1-on-1 only)	rolesStringArray	sendThreadedMessage.allowedReceiverRoles	null	null
Thread Category Filter	Select which message categories can be sent in threads	stringArray	sendThreadedMessage.allowedMessageCategories	message, custom	null
Thread Type Filter	Select which message types can be sent in threads	stringArray	sendThreadedMessage.allowedMessageTypes	text, image, audio, video, file	null
Thread Custom Types	Define custom message types that can be sent in threads	customStringArray	sendThreadedMessage.allowedCustomTypes	null	null
Thread MIME Type Access Control	Set MIME type filtering mode for threads to allow or deny	string	sendThreadedMessage.mimeTypeAccessControl	allow, deny	allow
Thread Media MIME Types	Define MIME types for thread media message filtering	customStringArray	sendThreadedMessage.mimeTypes	null	null
Thread Message Editing	Allow or deny editing of thread messages	string	editThreadedMessage	allow, deny	allow
Thread Message Deletion	Allow or deny deletion of thread messages	string	deleteThreadedMessage	allow, deny	allow

4. Message Reactions

Title	Description	Data Type	Permission Key	Available Values	Default
Reaction Listing	Allow or deny viewing message reactions	string	listReactions	allow, deny	allow
Reaction Management	Allow or deny adding/removing message reactions	string	addReaction	allow, deny	allow

5. Calls

Title	Description	Data Type	Permission Key	Available Values	Default
Call Initiation	Allow or deny call initiation functionality	string	initiateCall	allow, deny	allow
Call Receiver Type Filter	Select which receiver types can receive calls	stringArray	initiateCall.allowedReceiverTypes	user, group	null
Call Receiver Role Filter	Select which receiver roles can receive calls (1-on-1 only)	rolesStringArray	initiateCall.allowedReceiverRoles	null	null
Call Joining	Allow or deny joining 1-on-1 calls	string	joinCall	allow, deny	allow

6. Conversations

Title	Description	Data Type	Permission Key	Available Values	Default
List Conversation	Allow or deny conversations listing functionality	string	listConversations	allow, deny	allow
Update Conversation	Allow or deny conversation update functionality	string	updateConversation	allow, deny	allow
Delete Conversation	Allow or deny conversation delete functionality	string	deleteConversation	allow, deny	allow

7. Groups

Title	Description	Data Type	Permission Key	Available Values	Default
Group Listing	Allow or deny group listing functionality	string	listGroups	allow, deny	allow
Group List Type Filter	Select which group types can be listed	stringArray	listGroups.allowedGroupTypes	public, password, private	null
Group Details	Allow or deny details for a group	string	getGroupDetails	allow, deny	allow
Group Details Type Filter	Select for which group types details can be fetched	stringArray	getGroupDetails.allowedGroupTypes	public, password, private	null
Group Creation	Allow or deny group creation functionality	string	createGroup	allow, deny	allow
Group Creation Type Filter	Select which group types can be created	stringArray	createGroup.allowedGroupTypes	public, password, private	null
Group Joining	Allow or deny group joining functionality	string	joinGroup	allow, deny	allow
Group Join Type Filter	Select which group types can be joined	stringArray	joinGroup.allowedGroupTypes	public, password	null

RBAC Example Configuration

The following example denies the sendMessage permission for the user role. When applied, users with this role will not be able to send messages and will receive an ERR_PERMISSION_DENIED error.

{
  "permissions": {
    "sendMessage": "deny"
  }
}

RBAC Permission Evaluation Order

1. Explicitly configured permission for the role which has the highest priority
2. Permission default value (from permission definition)

If a permission is not explicitly configured for a role, the default value is used.

---

SBAC (Scope-Based Access Control)

Scope-Based Access Control (SBAC) enables fine-grained control over what actions a user can perform within a group, based on their member scope (for example: admin, moderator, participant).

How SBAC Works

• Permissions are configured per scope within group context
• Each permission has a default value
• Explicitly configured permissions override defaults
• SBAC permissions are evaluated at runtime for every group-related API request
• If a permission evaluation fails, the API returns an ERR_PERMISSION_DENIED error
• SBAC permissions are evaluated alongside RBAC rules. For group operations, both must allow the action

SBAC supports:

• Binary permissions (allow / deny)
• Conditional permissions using additional configuration keys such as allowedScopes, allowedMessageTypes, and mimeTypes

Permissions can be restricted by additional conditions such as:

• Member scopes within the group
• Message categories and types
• Group-specific message history access

SBAC Data Types

Data Type	Description	Example Values
string	Single string value	allow, deny
stringArray	Array of predefined strings	["admin", "moderator"], ["text", "image"]
customStringArray	Array of custom user-defined strings	["custom-type-1", "custom-type-2"]

SBAC Permission Structure

Each SBAC permission follows this structure:

Attribute	Description
Key	The SBAC permission key used in APIs
Category	Logical grouping (Groups, Members, Messages, etc.)
Data Type	Expected value type
Available Values	Supported values
Default	Applied if not explicitly configured

SBAC Permission Value Behavior

When an array permission (e.g., allowedScopes, mimeTypes) has a value of null:

• It means no restriction - all values are allowed
• This is equivalent to an empty array []

For allow / deny values:

• allow: The action is permitted
• deny: The action is blocked, returns ERR_PERMISSION_DENIED

SBAC Permissions

1. Groups

Title	Description	Data Type	Permission Key	Available Values	Default
Group Edit Details	Allow or deny group edits	string	editGroup	allow, deny	admin: allow moderator: deny participant: deny
Group Delete	Allow or deny group deletes	string	deleteGroup	allow, deny	admin: deny moderator: deny participant: deny
Group Leave	Allow or deny group leave	string	leaveGroup	allow, deny	allow

2. Members

Title	Description	Data Type	Permission Key	Available Values	Default
Member Listing	Allow or deny listing group members	string	listMembers	allow, deny	allow
Member List Scope Filter	Select which member scopes can be listed	stringArray	listMembers.allowedScopes	admin, moderator, participant	null
Member Addition	Allow or deny adding members to groups	string	addMembers	allow, deny	admin: allow moderator: deny participant: deny
Member Add Scope Filter	Select which member scopes can be added	stringArray	addMembers.allowedScopes	admin, moderator, participant	null
Member Removal	Allow or deny kicking members from groups	string	kickMembers	allow, deny	admin: allow moderator: allow participant: deny
Member Kick Scope Filter	Select which member scopes can be kicked	stringArray	kickMembers.allowedScopes	admin, moderator, participant	null
Banned Member Listing	Allow or deny listing banned members	string	listBannedUsers	allow, deny	admin: allow moderator: allow participant: deny
Member Banning	Allow or deny banning members from groups	string	ban	allow, deny	admin: allow moderator: allow participant: deny
Member Ban Scope Filter	Select which member scopes can be banned	stringArray	ban.allowedScopes	admin, moderator, participant	null
Member Unbanning	Allow or deny unbanning members from groups	string	unban	allow, deny	admin: allow moderator: allow participant: deny

3. Messages

Title	Description	Data Type	Permission Key	Available Values	Default
Message Category Filter	Select which message categories can be listed in groups	stringArray	listMessages.allowedMessageCategories	message, custom	null
Message Type Filter	Select which message types can be listed in groups	stringArray	listMessages.allowedMessageTypes	text, image, audio, video, file	null
Message History	Allow or deny listing messages sent before joining the group	string	listMessages.historyBeforeJoin	allow, deny	allow
Group Message Sending	Allow or deny sending messages in groups	string	sendMessage	allow, deny	allow
Group Send Category Filter	Select which message categories can be sent in groups	stringArray	sendMessage.allowedMessageCategories	message, custom	null
Group Send Type Filter	Select which message types can be sent in groups	stringArray	sendMessage.allowedMessageTypes	text, image, audio, video, file	null
Group Custom Message Types	Define custom message types that can be sent in groups	customStringArray	sendMessage.allowedCustomTypes	null	null
Group MIME Type Access Control	Set MIME type filtering mode for group messages to allow or deny	string	sendMessage.mimeTypeAccessControl	allow, deny	allow
Group Media MIME Types	Define MIME types for group media message filtering	customStringArray	sendMessage.mimeTypes	null	null
Group Message Editing	Allow or deny editing messages in groups	string	editMessage	allow, deny	allow
Group Message Deletion	Allow or deny deleting messages in groups	string	deleteMessage	allow, deny	allow

4. Message Thread

Title	Description	Data Type	Permission Key	Available Values	Default
Group Thread Listing	Allow or deny listing threaded messages in groups	string	listThreadedMessages	allow, deny	allow
Group Thread Sending	Allow or deny sending messages in group threads	string	sendThreadedMessage	allow, deny	allow
Group Thread Category Filter	Select which message categories can be sent in group threads	stringArray	sendThreadedMessage.allowedMessageCategories	message, custom	null
Group Thread Type Filter	Select which message types can be sent in group threads	stringArray	sendThreadedMessage.allowedMessageTypes	text, image, audio, video, file	null
Group Thread Custom Types	Define custom message types that can be sent in group threads	customStringArray	sendThreadedMessage.allowedCustomTypes	null	null
Group Thread MIME Type Access Control	Set MIME type filtering mode for group thread messages to allow or deny	string	sendThreadedMessage.mimeTypeAccessControl	allow, deny	allow
Group Thread Media MIME Types	Define MIME types for group thread media message filtering	customStringArray	sendThreadedMessage.mimeTypes	null	null
Group Thread Editing	Allow or deny editing thread messages in groups	string	editThreadedMessage	allow, deny	allow
Group Thread Deletion	Allow or deny deleting thread messages in groups	string	deleteThreadedMessage	allow, deny	allow

5. Message Reactions

Title	Description	Data Type	Permission Key	Available Values	Default
Group Reaction Listing	Allow or deny viewing message reactions in groups	string	listReactions	allow, deny	allow
Group Reaction Management	Allow or deny adding/removing message reactions in groups	string	addReaction	allow, deny	allow

6. Calls

Title	Description	Data Type	Permission Key	Available Values	Default
Group Call Initiation	Allow or deny call initiation in groups	string	initiateCall	allow, deny	allow
Call Joining	Allow or deny joining calls in groups	string	joinCall	allow, deny	allow

SBAC Example Configuration

The following example denies the sendMessage permission for the participant scope. When applied, group members with the participant scope will not be able to send messages in the group and will receive an ERR_PERMISSION_DENIED error.

{
  "permissions": {
    "sendMessage": "deny"
  }
}

SBAC Permission Evaluation Order

1. Explicitly configured permission for the scope which has the highest priority
2. Permission default value (from permission definition)

If a permission is not explicitly configured for a scope, the default value is used.