Migrating from Legacy

LAST EDIT Jul 22 2024
Depending on which client-side SDK you use, the custom permissions checking processes may not be implemented yet and could affect user experience. If you use our client SDKs, we recommend waiting to migrate until there is complete front end support, or test this thoroughly in development first. Updates will be posted here as we add more support.

The migration process is pretty straightforward and mostly automated, but you should consider these facts before you pull the trigger:

  1. Make sure backend of your app does not explicitly sets "permission_version" field to "v1" using UpdateApp API endpoint. This will cause your app to rollback to previous version of permission system

  2. There are some permissions properties which should no longer be used on v2 so it is good to understand how you are using them today

    1. "Permissions" field in UpdateChannelType will not affect new permission system. This field is kept for backward compatibility and it allows you to roll back to version 1 in case you changed your mind

    2. Do not use User.role, ChannelMember.channel_role to determine user capabilities. This kind of check is usually fragile and in case of configuration change, UI will not be representative of the new settings

    3. Do not use ChannelMember.role as it is displaying inconsistent values. This field is kept for backwards compatibility only

    4. Option user_search_disallowed_roles only works with permissions v1. To control set of users who can perform user search you should use application-level permission grants (.app scope)

  3. If you plan to use custom permissions, make sure your client code does not rely on direct role comparisons. Please see Channel Capabilities page for more info



In order to use version 2 of permissions system, make sure you use compatible version of SDK


Minimum version



React Native














iOS and Unreal SDKs don't support Channel Capabilities yet

We strongly recommend to regularly update your SDK dependencies since they constantly improve user experience, resolve bugs and add support for new features

How to migrate


We provide two options for performing a migration

Using Dashboard


When you open a Chat application overview for the app that uses older version of permissions, you will see a popup suggesting you to perform an upgrade.

Permission system upgrade dialog

Click "Upgrade" and wait until the page refreshes. Now you should be able to access new "Roles and Permissions" page to set up the permission settings.

You can also navigate directly to the "Roles & Permissions" page under chat settings and click "Upgrade" on the prompt shown there.

Roles & permissions upgrade prompt

This upgrade option translates old permission settings the new system automatically, but we encourage you to visit "Roles and Permissions" page to double check that the configuration is correct.

Using API


In order to migrate to permissions "v2" you have to perform exactly this API call to UpdateApp API endpoint:

permission_version field controls which permission system version is active. You can switch back and forth without providing any extra fields, but in order to convert all your existing configuration, you should provide "migrate_permissions_to_v2": true. When this flag is present, Chat API translates v1 configuration to v2 for you which ensures that your app functions properly without any interruptions. You can always switch back to v1, but configuration translation only works one way. You can also prepare permissions v2 configuration manually and switch to the new version without providing migrate_permissions_to_v2 flag

We recommend you to take a good look at the resulting grants configuration and make sure that all permissions there are correct. Even better if you can test these configurations in development before updating production

How to switch back


In case something goes wrong for you, you can switch back to legacy permission system:

New Global Roles


*For multi-tenant applications only*

Once you migrate to v2 permissions there will be two new roles available. These roles allow users to be Admins or Moderators across all teams. Previously, all users had to belong to a team and could only access channels and messages belonging to the same teams. These new roles allow access to all teams data and are important for users of the Stream Dashboard.

To change the role of Admin Users to Global Admin, or to change the role of Moderators to Global Moderator, you can use UpdateUser API endpoint: