Roles & Permissions

Once Chatkit authenticates a user's request and verifies their identity, it must then decide if that user has permission to perform the requested action. This is where the roles and permissions process comes in.

Roles

Users are assigned roles, which contain a set of permissions describing what actions they can and cannot do. Chatkit will check the user's roles before carrying out the requested action. Chatkit allows you to define a set of roles within your Chatkit instance. A role can either be applicable to specific rooms or it can be scoped globally, meaning it's applicable at an instance-wide level.

When a Chatkit instance is created it comes with two pre-defined roles. They are called admin and default and are both scoped globally. The admin role is permitted to perform any action while the default role is more restricted and permits only a subset of the available actions to be performed by a user. The default role cannot be deleted but the permissions associated with it can be edited.

A user is always assigned a single globally scoped role. You can change which globally scoped role a user is assigned by making a request to the Chatkit servers where you specify the user ID and the role you wish to assign to the user. Users are assigned the default global role by default.

When a user makes a request to the Chatkit servers, the user ID is first extracted from the JWT (JSON Web Token) that accompanies the request. Using that user ID, the user's roles and their associated permissions are retrieved. The permissions required for the request are then compared against the set of permissions that the user has been given, as determined by their roles, and the request is either permitted or rejected.

A user can be associated with as many room scoped roles as is appropriate for an app's needs. When you wish to associate a user with a room scoped role you make a request to the Chatkit servers specifying the role and the ID of the room you wish to associate the user with.

If a user makes a request that is relevant to a specific room and the user has a room specific role assigned to them, then the permissions attached to the room specific role are combined with the permissions attached to their globally scoped role, whether that be the default role or otherwise, and the combined set of permissions is then used to check if the request should be permitted or rejected.

Permissions

Depending on whether a role is scoped to an individual room or globally, it can have different permissions associated with it.

If you're creating a globally scoped role then these are the permissions that you can add to it:

  • room:join - user can join any public room
  • room:leave - user can leave any room
  • room:members:add - user can add new members to any room
  • room:members:remove - user can remove existing members from any room
  • room:create - user can create new rooms (public and private)
  • room:delete - user can delete any room
  • room:update - user can update any room
  • message:create - user can add messages to any room (that they're a member of)
  • room:typing_indicator:create - user can create typing events in any room
  • presence:subscribe - user can subscribe to get presence information
  • user:update - user can update any user's information
  • user:get - user can get information about any user
  • room:get - user can get information about any room
  • user:rooms:get - user can get a list of rooms that any user is a member of
  • cursors:read:get - user can get and subscribe to updates to read cursors in rooms that they are a member of
  • cursors:read:set - user can set their own read cursor in rooms that they are a member of
  • file:get - user can download message attachments from the room
  • file:create - user can upload message attachments into the room

If you're creating a room scoped role then these are the permissions that you can add to it:

  • room:join - user can join the room (provided it is a public room)
  • room:leave - user can leave the room
  • room:members:add - user can add new members to the room
  • room:members:remove - user can remove existing members from the room
  • room:delete - user can delete the room
  • room:update - user can update the room
  • message:create - user can add messages to the room
  • room:typing_indicator:create - user can create typing events in the room
  • cursors:read:get - user can get and subscribe to updates to read cursors in the room
  • cursors:read:set - user can set their own read cursor in the room
  • file:get - user can download message attachments from the room
  • file:create - user can upload message attachments into the room

Initial App Permissions

As described in the roles section, every app begins with two globally scoped roles; default and admin. While the permissions associated with these roles can be changed, the initial permissions are as follows:

default Role:

  • message:create
  • room:join
  • room:leave
  • room:members:add
  • room:members:remove
  • room:get
  • room:create
  • room:messages:get
  • room:typing_indicator:create
  • presence:subscribe
  • user:get
  • user:rooms:get
  • cursors:read:get
  • cursors:read:set
  • file:create
  • file:get

admin Role:

  • All of the default role permissions
  • room:delete
  • room:update

Examples

Here are a few examples of how the roles and permissions process works when a request is made to the Chatkit servers.

In all of the examples we'll assume that the user making the request has a user ID of sarah.

Example 1

sarah makes a request to add a message to the room with ID 123, which she is a member of.

The Chatkit servers check to see if any roles have been assigned to a user with ID sarah. The globally scoped role assigned to sarah has not been updated since her user was created, nor have any roles been assigned to sarah that are tied to the room with ID 123.

Therefore, the only role sarah has assigned to her is the default globally scoped role. The Chatkit servers then check if it has the message:create permission.

sarah is in luck; the default role does have the message:create permission and so her message gets added to room 123.

Example 2

sarah is a member of room 29, which is a private room. sarah wants her friend ryan to join the room, but he can't as it's a private room. However, sarah thinks she might be able to add ryan to the room so she makes a request to add him to the room.

No global roles are found for sarah but there is a room scoped role for room 29, which is tied to sarah. It has the room:members:add permission attached to it and so sarah's attempt to add ryan to room 29 succeeds.

Note that it succeeded even though ryan didn't have permission to join the room himself.

Example 3

sarah wants to delete room with ID 88 and so she makes a request to attempt to do so.

The only room-specific role that exists for sarah is tied to room 9, so that is ignored.

There is a global role that sarah has been assigned, but it doesn't have the room:delete permission. As a result the request is rejected with a 403 status code.

What's Next?

Now that you've read up on roles and permissions, learn how to set them using the roles and permissions HTTP endpoint directly.

Did you find this document useful?

We are always striving to create the most accurate and informative docs as possible. If there is something especially wrong (or right) here then please let us know.