📘

Granular scopes

Zoom introduced new "granular" scopes in April 2024 to replace their Legacy scopes. Existing apps are unaffected, but any newly created apps will use these new granular scopes.

For previously created apps using Legacy scopes, see Zoom OAuth Setup.

1. Zoom App Setup

---

Create the App

Navigate to the Zoom App marketplace and create a new app:

Select how your users will manage your app:

• User-managed: Individual end users authenticate via OAuth
• Account-managed: Zoom account admins authenticate the app for their entire organization

📘

In general, if your app serves individual end users, you should default to User-managed. If your app is used by entire organizations, you should use admin-managed.

Scopes

For the Zoom OAuth integration to work properly, we need to include a several OAuth scopes.

These are different for user-level and account-level apps - make sure to select the scopes accordingly.

User-level (user-managed) scopes

From Meeting:

• meeting:read:local_recording_token: Required to grant the bot local recording permission
• meeting:read:list_meetings: Required to list all meetings for a user

From User:

• user:read:user: Required for retrieving user's PMI
• user:read:zak: This scope is only required if you're using the same Zoom app for meeting SDK functionality (configured in the Recall dashboard) and your OAuth integration. If you're using a separate app for OAuth, this scope should be omitted.

For the scope description, we recommend the following:

These scopes are used to give local recording permissions to meeting bots on behalf of the user. The user's ID as well as their meeting ID's (including their PMI) are stored in order to know which meetings to generate local recording join tokens for. All data is encrypted at rest.

Account-level (admin-managed) scopes

From Meeting:

• meeting:read:list_meetings:admin: Required to view all meetings for a given user
• meeting:read:local_recording_token:admin: Required to grant the bot local recording permission

From User:

• user:read:list_users:admin: Required for retrieving the Zoom account's users and their personal meeting ID's (PMI)

In the Scope Description, we recommend the following response:

The local recording token scope is used to give meeting bots recording permission. The list users scope is used to retrieve all users for the Zoom account. The list meetings scope is used to get all meetings for a given user in the workspace. The users' meetings and account ID are stored in a database and are encrypted at rest.

Save your app details

Once you've set up your Zoom app, you should save the following 3 pieces of information from your Development application:

• Zoom App Client ID
• Zoom App Client Secret
• Zoom App Secret Token

Your client ID and client secret can be found under Build your app > Basic Information or simply in the Application Credentials card in the top left.

The Zoom App Secret Token can be found under Build your app > Features > Access

We recommend storing these in a .env file for local development. This will make it simple to change these values to the corresponding production credentials when your Zoom app is approved.

2. Create the OAuth App in Recall

---

To create the Zoom OAuth App in Recall, send a POST request to the Create Zoom OAuth App endpoint.

The body should include:

• kind: user_level or account_level depending on your app
• client_id: The client ID from the previous step
• client_secret: The client secret from the previous step
• webhook_secret: The secret token from the previous step

For simplicity, you can create this directly from the Create Zoom OAuth App API reference:

⚠️

Keep the returned ID!

Store the id returned in the response somewhere easily accessible - you'll need this in the following steps.

This is your Recall Zoom OAuth App ID.

3. Configure webhooks

---

In order to automatically fetch tokens for a user's Zoom meetings, Recall needs a way to stay in sync with Zoom as new meetings are created.

To do this, we have to configure our Zoom app to send webhooks to a Recall endpoint - a webhook endpoint specific to the Zoom OAuth app you just created in the last step.

Add events

Click the "Add Events" button and select the following events:

Meeting > Meeting has been created

User > User's profile info has been updated

This is required to keep the personal meeting ID of the user in sync.

Add the event notification endpoint URL

Build your webhook URL using your Recall Zoom OAuth App ID:

https://api.recall.ai/api/v2/zoom-oauth-apps/{RECALL_ZOOM_OAUTH_APP_ID}/webhook

Note: These should be the same for both development and production

📘

If your server needs to receive these webhooks:

• Enter your own server's webhook endpoint in these fields
• Forward every Zoom webhook received to the Recall endpoint constructed above
• You must include the x-zm-request-timestamp and x-zm-signature headers.
• You must not modify the webhook body in any way. This includes any re-ordering of parameters that might happen when deserializing and re-serializing.

Enter this in the Event notification endpoint URL and save the event subscription.

✅

Your Zoom app is now set up for the Recall OAuth integration. Almost there!

Recall vs customer managed OAuth

---

The next (and final) step is to implement the OAuth flow for your users in order to actually connect their Zoom accounts.

Once a user has gone through the OAuth flow, you can either manage access and refresh tokens on your end or have Recall manage these for you.

In general, we highly recommend using Recall-managed OAuth by default, unless:

• You already have an integration with the Zoom OAuth API.
• You need to call the Zoom API endpoints for other functionality in your app.

☑️

Before continuing

Make sure you have these saved for the final step:

• Zoom App Client ID
• Zoom App Client Secret
• Zoom App Secret Token
• Recall Zoom OAuth App ID