Migrate from classic to granular scopes

Your existing apps can continue to use classic scopes, but we encourage you to migrate them to use granular scopes. Follow the steps in this guide to do so.

Before Migration

If your app is leveraging the scope values returned by the access token, you should be sure to update your code to handle the proper values before the migration process to ensure there are no breaking changes. See access tokens for details.

If your app does not leverage the scope values, there is no preparation necessary.

Migration Process

Start the migration in the build flow for each app that you would like to migrate.

In the web portal, click manage to see your list of apps.
Select an app that you want to migrate to granular scopes and click to edit your app.
In the build flow for your app, click Feature and find the Scope page on the Development tab. On the scope page, find the message related to granular scopes, which shows a Migrate button.
Click the Migrate button to begin.
You'll see a prompt showing an example of a classic to granular scope migration. Click Migrate scopes to confirm the migration. This example is static, it does not reflect your current scope selection.
Once confirmed, Zoom automatically assigns granular scopes to your app. Specifically, Zoom looks at the APIs and events that your app can access based on the classic scopes you assigned to your app and assigns the respective granular scopes.
After the migration on the Development tab, you can see the granular scopes on the page. Review this list of granular scopes and may remove any scopes that are no longer necessary for your app.

Keep in mind that the selected scopes will be displayed by default to end users when they are authorizing your app. You may want to consider removing some of these or making them scopes optional if they are not required. You won't have this option when you migrate to Production as it will just copy your Development scopes (see the following steps for details).
Test your app and scopes to be sure they operate as you expect.
Once you have tested and are ready to migrate production users of your app to granular scopes, go to the Production tab and click the Migrate button.

If your app is in draft mode or only shared internally, the migrate button is only available in Development.
Similar to the migrating step for the Development tab, you'll see the prompt with a static example that asks you to confirm that you want to migrate your scopes.

Click Migrate scopes to do so. Once you confirm, Zoom copies your app's granular scopes from Development to Production (since you already reviewed the scopes in the Development tab, there is no need to review them again).

You do not have to resubmit your app for review and approval if you are only migrating classic scopes to granular scopes or reducing the number of required scopes. However, if you add new granular scopes, you must submit your app for review and approval before the migration will take effect in Production.
Once you've completed the migration, new users who add your app will see granular scopes when they authorize it. Your app will also be ready to leverage optional scopes.

After Migration

Once you've migrated your app to use granular scopes, be aware of the following changes to access tokens and the end user authorization experience.

Access tokens

Access tokens for existing users and new users will operate differently after migration. See this section for details.

Access and refresh tokens for existing users

For apps created before the release of granular scopes, apps authorized by existing users will use access tokens and refresh tokens that will continue to work. The values for the scope parameter within each access token will continue to return the values for classic scopes.

However, if existing users or accounts have to go through authorization again, Zoom will issue a new access token. In this new token, the scope parameter will contain values for granular scopes and the previous token will be invalidated.

Access and refresh tokens for new users

Once migration is completed, the scope value in access tokens for users and accounts authorized from this point will contain values for granular scopes.

End User Authorization Experience

Existing users who have already authorized your app do not need to reauthorize.

New users who have yet to authorize your app will see the new authorization page with granular scopes and optional scopes after your app has finished the migration in the Production tab.