# Roles and Permissions

<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->

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

1. A user will always have access to apps they are approved to use.
1. Role-based permissions are consistent for apps and the user experience.
1. 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.