Integrations - OAuth scopes

In order to provide a better experience for users, Zoom is introducing granular and optional scopes to allow users to be more specific about the level of access granted to third-party apps. Users will be more encouraged to use your app if you reduce the permissions to the least amount necessary to run your app.

• Newly created apps use granular scopes, including new apps created using the new build flow, new Server-to-server apps, and new apps using the legacy build flow. New apps can also set which scopes are required and which are optional. See the rest of this page for details.
• Previously-created apps use the previously-available scopes, now called classic scopes. If you upgrade your app you will still be able to use classic scopes. You can migrate your User OAuth apps from classic to granular scopes. See Migrate scopes for details.

Classic scopes#

Classic scopes provide a way to limit the amount of access granted to an app. Zoom has user-level, admin-level, and Master-level scopes:

• User-managed apps can only request scopes that allow access to an individual user's associated data.
• Admin-managed apps have admin scopes and provide admin capabilities. The user adding the app must be an account admin or owner in order to be granted admin capabilities.
• Master-level scopes can only be granted to an an account-level app by account owners.

See Classic Scopes for a complete list of scopes, their descriptions, and the associated API calls that the app with permitted scope has access to.

An application can set one or multiple scopes while registering their OAuth app in the Zoom App Marketplace.

See shared access permissions for important details about your app's access to information.

Granular scopes#

Granular scopes enable developers to practice the principle of least privilege so that users can provide access to the minimal amount of information required by your app. Users can choose specific permissions for your app rather than being overly permissive with classic scopes.

Definition#

Granular scopes are defined in the following format.

<service>:<action>:<data_claim>:<access>

• Service - The type of Zoom's service that the permission is given to. For example, meeting or webinar
• Action - The action of which the party is granted the permission for. Different from classic scopes, there are total of 4 actions in granular scopes: read, write, update and delete.
  • read - GET endpoints, events or methods that retrieve data only use the read action.
  • write - POST endpoints or methods that create or add data into Zoom use the write action.
  • update - PATCH and PUT endpoints or methods that update or re-write existing data entry in Zoom use the update action.
  • delete - DELETE endpoints or methods that remove or hard delete existing data entry in Zoom use the delete action.
• Data claim - The general descriptions of the data categories that are contained within the endpoints, events or method. For example, meeting.read.participants indicates meeting participants data is governed by this access scope. Similarly, phone.read.participant indicates phone participants data is governed by this access scope.
• Access - The level of access that ties into the scope. There are 3 possible values: null value, admin and master.
  • null value - An empty value. Access scope without an access value indicates the scope is tied to data claims that can be granted by individual users.
  • admin - The access scope is tied to data claims that can only be granted by users with administrator role.
  • master - The access scope is tied to data claims that can only be granted by users with administrator role in a master account in the master-sub account set up.

Prerequisites#

• Account administrators or users with role-based access permission to view and manage applications in the Zoom Marketplace can use granular scopes.

The administrator for a Zoom account can give a user these permissions. In the Zoom web portal, the administrator must go to User Management > Roles > Role Settings > Advanced Features and select the View and Edit check boxes for Zoom for developers and any other apps in this section that the administrator wants to enable the user to access.

Limitations#

• Some resources may not yet have granular scopes available for them. More granular scopes from different resources will be made available in the future. If there are granular scopes that you believe are missing, please contact support.

Build flow with granular scopes#

The granular scopes experience is mostly unchanged compared to the existing classic scopes experience. The only difference is that scopes are now more specific. Classic scopes and granular scopes do not exists in the same app. If an app is using classic scopes, that app will not see granular scopes in the build flow. Vice versa, if an app is using granular scopes, that app will not see classic scopes in the build flow. The following describes the build flow.

1. Create a new application in the Zoom Marketplace.
2. Under Scopes, click Add Scopes.
3. Select the granular scopes you'd like to use in the app.
4. Once you've selected the granular scopes, you'll see a list of the granular scopes you selected and their descriptions.
   • In that list, you can mark a scope Optional. Scopes not marked as optional will be required when using the basic authorization query.
   • Choose to require the minimal amount of scopes for your app.
   • The scopes you choose set the boundaries for your app's permissions.
   • You can continue to add or remove scopes for your app.
5. After you've chosen your scopes, continue the process to add or publish the app.
6. After the user authorizes the app, you can use the access token and call the API endpoints. To see which scope associates to which endpoints and webhook events, see Granular scopes for the granular scopes reference documentation.

Optional scopes#

Optional scopes enable developers to use granular scopes in their app that users can choose to enable if they want the advanced features that require access to more of their data. These scopes should be related to additional capabilities your app or integration can offer. These capabilities should not be required for your app or integration to function.

By designating some granular scopes as optional, you can build sophisticated apps that can use a larger set of scopes, without requiring that users give access to more data than they choose. Instead, you can create a version of the app that uses minimal granular scopes and access to information, and leave it to the user to decide to give more permissions and more access to use more features.

Authorization#

Your app can obtain access tokens using the following methods.

1. Basic authorization query uses the default required and optional scopes set by the developer in the build flow.
2. Advanced authorization query enables developers to designate which scopes are required and which are optional, regardless of their settings in the build flow.

Basic authorization query#

To initiate an authorization, an app can call the basic authorization query

https://zoom.us/oauth/authorize?response_type=code&client_id={your_client_ID}&redirect_uri={your_oauth_redirect_URL}

This brings the user to the authorization page where they can review and grant permissions for both required and optional scopes.

The optional scopes on the page will be the default optional scopes, marked as optional in the build flow. The required scopes on the page will be the default required scopes that the developer did not mark as optional in the build flow.

Advanced authorization query#

To customize which scopes are required and which are optional, an app can call the advanced authorization query.

https://zoom.us/oauth/authorize?client_id={clientID}&response_type=code&redirect_uri={redirect_uri}&scope={mandatory_granular_scopes}&optional_scope={optional_granular_scopes}

The following parameters determine the scopes.

• scope - set the required scopes for the app for this authorization attempt.
• optional_scope - set the optional scopes for the app for this authorization attempt.

Note that the scopes must have already been added to the app in the build flow.

By using optional scopes, users don't need to authorize every single scope the app is asking for in a single attempt. Instead, you can configure your app to make subsequent authorization requests to obtain additional scopes to enable additional functionalities within the app, as needed. This can provide better transparency to your users as they can be more aware that a new feature or capability requires a new scope.

To obtain new scopes in addition to scopes which the app had already had from previous authorization, an app can use the following query

https://zoom.us/oauth/authorize?client_id={clientID}&response_type=code&redirect_uri={redirect_uri}&include_granted_scopes&scope={additional_granular_scopes}&optional_scope={additional_optional_scopes}

• include_granted_scopes - return an access token that includes all of the user's previously authorized scopes once they complete the current authorization request.

If the user or the customer has previously authorized some scopes, but your app uses an authorization query without include_granted_scopes, Zoom will assume that your app wants to limit the requested scopes to only the newly authorized ones.

User experience#

When users authorize apps that using granular scopes, they will see the required granular scopes and descriptions on the authorization page.

When users authorize an app that has optional scopes, they will see both the required scopes and the optional scopes during initial authorization. Zoom presents these as required or optional permissions for your app.

Users can select all, some, or no optional permissions during authorization.

If a user doesn't authorize certain optional permissions that the app requires for specific capabilities, the app can initiate a subsequent advanced authorization query attempt where to require the scope. This will bring the user back to the Zoom authorization page to allow or decline the permission.