Roles and Permissions

The role-based permissions API framework has three key principles:

  1. A user will always have access to apps they are approved to use.
  2. Role-based permissions are consistent for apps and the user experience.
  3. Developers have choice in how they leverage the framework to create an app experience that is useful given available permissions.

With the role-based permission framework, you can make your app work for Meeting Owners and Participants based on the data they have rights to share with your app. The Meeting Owner (the person who the meeting is scheduled under and who therefore is the initial meeting host) sets the rules and owns the data about a meeting. A Participant, by contrast, only has access to their user data and can do things like share their display name with an app.

An app that has only access to a single Participant's data in a meeting may not be fully functional. But if the app has a second user's data, even if that user is only another Participant, you can construct a collaborative use case.

Below are the technical details on how to shift to role-based permissions, so users will always have access to your app if they are approved to use it.

Determine which methods the user has permissions to use

  • Calling an unsupported method from an app instance by a participant who is not the owner will result in an error (code 403: Permission denied).
  • Your app may also call one of the following:
    • getSupportedJsApis returns a list of APIs that the current app user can use
    • config returns unsupportedApis, a list pf APIs that the current user doesn't have the appropriate permissions to use.
  • Any role limitations are noted in the API documentation for each endpoint and event.

Transition from individual to collaborative experience

How to (re)construct an application so it can seamlessly transition from an individual experience (single player mode) to a collaborative one (multiplayer mode) using this model:

  1. Only request app scopes, methods and events that your application actually needs. This reduces the "scary factor" when a user first installs your app. It also helps Zoom to identify the impact of changes in the future.

  2. Consider an app model that always starts out as a personal app. This should be useful to an individual participant in a meeting (or even outside a meeting), when no data about that meeting or other participants is available from Zoom.

  3. Leverage the Universal Meeting Id (Meeting UUID) to consolidate state about multiple users from the same meeting in your app backend. Remember each app instance running in the participant's Zoom client can call their individual getUserContext to map their running app instance to their participantId and name.

    Each user owns that data and (subject to your data policies) can share that information with your app backend, and on to other users of your app within the meeting.

    In addition, the meeting owner can also access the full list of participants with their names along with Meeting Topic and Meeting Id, the meeting Owner owns this data and again, they can share this data with your app.

  4. Don't attempt to use the Meeting Id to do the meeting participant mapping described above. Remember that Zoom Meeting Topic and the Meeting Id could contain sensitive information. Also, practically speaking, a Meeting Id could be re-used for multiple meeting instances by a single user, and eventually the Zoom system will re-assign Meeting Id's that have not been in use for some time. In other words, Meeting Id_s are not guaranteed to be unique.

  5. If your app needs the owner to perform actions, and you have detected that the meeting owner does not have your app running, consider sending the app to that participant using sendAppInvitationToMeetingOwner.

  6. Remember that not all participants in a meeting (including the owner) will be able to install your app, for example if participants are from different organizations with different policies. Also, the owner might leave the meeting. It is important that your app is able to provide collaborative or "single player" experience for available participants when possible or fail gracefully.

  7. Mapping a calendar entry to an in-meeting instance is challenging. The most robust mechanism for this would be for the user to confirm (in your app) which calendar event they are participating in on Zoom. Remember that there could be overlapping meetings, even with the same Meeting Id in some situations.