Permissions v2 (Beta)

LAST EDIT Nov 16 2021
This page explains how to use Stream's permissions version 2, if you are looking for version 1, go here.

Getting Started

Copied!

There are multiple important terms to understand when it comes to permission management. Each permission check comes down to three things:

  • Subject - an actor which attempts to perform certain Action. It could be represented by a User or by a ChannelMember

  • Resource - an item that Subject attempts to perform an Action against. It could be a Channel, Message, Attachment or another User

  • Action - the exact action that is being performed. For example CreateChannel, DeleteMessage, AddLinks

The purpose of permission system is to answer a question: is Subject A allowed to perform Action B on Resource C?

Stream Chat provides several concepts which help to control which actions are available to whom:

  • Permission - an object which represents actions a subject is allowed to perform

  • Role - assigned to a User or Channel Member and is used to check their permissions

  • Grants - the way permissions are assigned to roles, applicable across the entire application, or specific to a single channel type or channel.

Also important to know is permissions checking only happens on the client-side calls. Server-side allows everything so long as a valid API key and secret is provided.

Role Management

Copied!

To make it easy to get started, all Stream applications come with several roles already built in with permissions to represent the most common use cases. These roles can be customized if needed, and new roles can be created specific for your application

This is the process of assigning a role to users so they can be granted permissions. This represents Subject A in the permissions question. Users will have one role which grants them permissions for the entire application and additionally users can have channel roles which grant permissions for a single channel or for all channels with the same channel type.

By default all users have builtin role user assigned. To change the role of the User, you can use UpdateUser API endpoint:

Once you add user to the channel, channel_member role will be assigned to user's membership:

In order to change channel-level role of the user, you can either add user to the channel with a different role or update it later:

Subject

Copied!

Subject can be represented by User or ChannelMember. ChannelMember subject is used only when user interacts with a channel that they are member of. Both User and ChannelMember have Role and permission system takes both roles into consideration when checking permissions.

Builtin roles

Copied!

There are some builtin roles in Stream Chat that cover basic chat scenarios:

Role

Level

Description

user

User

Default User role

guest

User

Used for guest users created by server-side endpoints. Guests are short-lived temporary users that could be created without a token

anonymous

User

Anonymous users are not allowed to perform any actions that write data. You should treat them as unathenticated clients

admin

User

Role for users that perform administrative tasks with elevated permissions

channel_member

Channel

Default role that gets assigned when user is added to the channel

channel_moderator

Channel

Role for channel members that perform administrative tasks with elevated permissions

It's worth noting that you cannot use user-level roles as channel-level roles vice-versa. This restriction only applies to builtin roles

Custom Roles

Copied!

In more sophisticated scenarios custom roles could be used. One Stream Chat application could have up to 25 custom roles. Roles are simple, and require only a name to be created. They do nothing until permissions are assigned to the role. To create new custom role you can use CreateRole API endpoint:

To delete previously created role you can use DeleteRole API endpoint:

In order to delete a role, you have to remove all permission grants that this role has and make sure that you don't have non-deleted users with this role assigned. Channel-level roles could be deleted without reassigning them, although, some users could loose access to channels where this role is used.

Once you have a role created you can start granting permissions to it. You can also grant or remove permissions for built in roles.

Granting Permissions

Copied!

User access in Chat application is split across multiple scopes. Each channel type has its own permission scope and one special scope .app is used to control permissions outside of certain channel types (e.g. accessing and modifying other users, accessing moderation APIs). Additionally, channel type permissions scope can be overridden for a single channel to provide individual channel permissions.

To list all available permissions you can you ListPermissions API endpoint:

You can also find all available permissions on Permissions Reference page

Each permission object contains these fields:

Type

Description

Description

Example

id

string

Unique permission ID

create-message-owner

name

string

Human-readable permission name

Create Message in Owned Channel

description

string

Human-readable permission description

Grants action CreateMessage which allows to send a new message, user should own a channel

action

string

Action which this permission grants

CreateMessage

owner

boolean

If true, Subject should be an owner of the Resource

true

same_team

boolean

If true, Subject should be a part of the team that Resource is a part of

true

To manipulate granted permissions for certain channel type, you can use UpdateChannelType API endpoint:

This call will only change grants of roles that were mentioned in the request. You can remove all role grants with providing empty array ([]) as list of granted permissions:

If you want to reset the whole scope to default settings, you can explicitly provide null to grants field:

You can manipulate .app scope grants using UpdateApp API endpoint in exactly the same way:

Channel-level permissions

Copied!

In some cases it makes sense to slightly modify granted permissions for the channel without changing channel-type grants configuration. For this, you can use Grants Modifiers that you can set for each channel individually. Grants Modifiers look almost exactly the same as regular Grants object except it allows to revoke permissions as well as grant new ones. For example, if we want to disallow sending links for users with role "user" in channel "livestream:example" and allow creating reactions, we can do this:

Exclamation mark (!) here means "revoke" and you can combine any number of "revoke" and "grant" modifiers