Migrating from Legacy
Confused about "Migrating from Legacy"?
Let us know how we can improve our documentation:
The migration process is pretty straightforward and mostly automated, but you should consider these facts before you pull the trigger:
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
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
"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
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 settingsDo not use
ChannelMember.role
as it is displaying inconsistent values. This field is kept for backwards compatibility onlyOption
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)
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
Prerequisites
Copied!Confused about "Prerequisites"?
Let us know how we can improve our documentation:
In order to use version 2 of permissions system, make sure you use compatible version of SDK
SDK | Minimum version |
---|---|
React | v7.0.0 |
React Native | v4.0.0 |
Angular | v2.2.0 |
Android | v4.27.0 |
iOS | v4.0.0 |
Flutter | v3.4.0 |
Unreal | v1.0.0 |
Unity | v1.0.0 |
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
Copied!Confused about "How to migrate"?
Let us know how we can improve our documentation:
We provide two options for performing a migration
Using Dashboard
Copied!Confused about "Using Dashboard"?
Let us know how we can improve our documentation:
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.
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.
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
Copied!Confused about "Using API"?
Let us know how we can improve our documentation:
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
How to switch back
Copied!Confused about "How to switch back"?
Let us know how we can improve our documentation:
In case something goes wrong for you, you can switch back to legacy permission system:
New Global Roles
Copied!Confused about "New Global Roles"?
Let us know how we can improve our documentation:
*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: