Migrating from Legacy

LAST EDIT Nov 16 2021
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

How to migrate

Copied!

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

Copied!

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

New Global Roles

Copied!

*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: