Using Zoom APIs

Zoom APIs allow developers to request information from the Zoom, including (but not limited) to user details, meeting reports, dashboard data, as well as perform actions on the Zoom platform on a user's behalf. For example, creating a new user or deleting meeting recordings.

On this page

Authentication

Zoom must authenticate each HTTP request made to the Zoom API. Zoom supports the use of OAuth 2.0 and JWT for authentication.

Using OAuth 2.0

OAuth 2.0 lets applications obtain access to Zoom resources, such as the user's profile information, via the Zoom API.

The following sections provide an overview on the OAuth protocol. To begin using the OAuth protocol for your app's authentication with Zoom, you must create either an OAuth app or a Server-to-Server OAuth app in the Zoom App Marketplace.

OAuth roles

The OAuth protocol defines four specific roles. These roles are actively involved in the process of authentication with Zoom APIs:

  • Resource Owner — A user in a Zoom account who can either authorize or decline a Client from accessing information related to the user's Zoom account.
  • Resource Server — The server that hosts the resource. If your app is integrating with the Zoom API to obtain user-related information, then the Zoom API server is considered the resource server.
  • Client — The application that requests access to the user's information. If your app makes access requests to the Zoom API, then your app is considered the Client.
  • Zoom Authorization Server — The authorization server issues access tokens to the client after successfully authenticating and obtaining authorization from the resource owner.

User-authenticated

Generally, the interaction between a Client (your app), a Zoom user, Zoom's authorization server, and the Zoom API follows the flow in the diagram below.

The Zoom authorization process
  1. The Client (your app) requests authorization from the Zoom user to access the user's information.
  2. The user authorizes the app and the app receives an Authorization Grant.
  3. The app presents the Authorization Grant to the Zoom Authorization Server to verify that it has received the user's permission to access user information.
  4. The Zoom Authorization Server acknowledges that user has permitted the app with requested access and it sends an Access Token along with a Refresh Token back to the app. The access token must be used as a means of authentication while making API calls to the Zoom API Server.
  5. The app calls the Zoom API to access requested resource by including the Access Token in the request as a means of authentication. When an access token expires, it becomes invalid. In this case, the client must use the Refresh Token to request another valid access token.
  6. After the Zoom API server authenticates the app, it sends back the Requested Resource in the form of a JSON response. If the authentication fails, an error is thrown stating what caused the error.

Server-to-Server authentication

Server-to-server authentication does not require the end user to authorize the app to access the user’s information. Here’s a diagram that shows this flow:

The Zoom Server-to-Server authorization flow

The Server-to-Server OAuth app type skips the end user authorization step as well as the redirect URL and refresh token.

OAuth grant types

An Authorization Grant is the authorization assigned to the Client by the resource owner. The grant type refers to the method the Client uses to request authorization.

OAuth 2.0 supports various grant types. However, with Zoom APIs, you should use either the Authorization Code or Client Credentials grant types.

Authorization Code

An Authorization Code is the most commonly-used grant type for Zoom APIs. The usage of this grant type is described in detail in the OAuth with Zoom guide.

The following steps provide an overview of the Authorization Code grant flow:

  1. The Client directs the user to the Zoom authorization server. The user will see a dialog box with permission request for access. This process is provisioned by Zoom via the Publishable URL. When a user tries to add your app, the user will be directed to the Zoom API authorization endpoint. To test it with your app locally, copy the Testable URL of your app and open it in a browser. A page similar to the one shown in the image below appears:
An example of the permission request dialog box.
  1. The user clicks Authorize.
  2. The user is redirected to the app's redirect_url along with an Authorization Code in the query string. The URL with the Authorization Code resembles following URL: https://yourappsredirecturl/?code={theauthorizationcode}
  3. The Client makes a request to Zoom to exchange the Authorization Code for an access token.

Example Node.js request access token with Client Credentials

var request = require('request');
var options = {
method: 'POST',
url: 'https://zoom.us/oauth/token',
qs: {
grant_type: 'authorization_code',
//The code below is a sample Authorization Code. Replace it with your actual Authorization Code while making requests.
code: 'B1234558uQ',
//The uri below is a sample redirect_uri. Replace it with your actual redirect_uri while making requests.
redirect_uri: 'https://abcd.example.com',
},
headers: {
/**The credential below is a sample base64 encoded credential. Replace it with "Authorization: 'Basic ' + Buffer.from(your_app_client_id + ':' + your_app_client_secret).toString('base64')"
**/
Authorization: 'Basic abcdsdkjfesjfg',
},
};
request(options, function (error, response, body) {
if (error) throw new Error(error);
console.log(body);
});

Client Credentials

The Client Credentials grant is used to get an access token for APIs that require only a service's permission. This grant does not require a user's permission.

For Zoom APIs, use the Client Credentials grant to get an access token from Zoom for the Server-to-Server OAuth app type or to get an access token from the Chatbot service in order to use the Send Chatbot Messages API.

To use Client Credentials grant type, perform the following steps:

  1. Navigate to your app's dashboard in the Zoom App Marketplace.
  2. In the App Credentials section of your app, copy your app's Client ID and Client Secret information.
  3. Make a POST request to the https://zoom.us/oauth/token?grant_type=client_credentials Zoom Authorization Endpoint URL. The value of the grant_type query parameter is set as client_credentials to indicate the Client Credentials grant type.
  4. Use the Basic access authentication Header and provide the base64-encoded string of your Client ID and Client Secret as credentials.

Example Node.js request access token with Client Credentials

var request = require('request');
var options = {
method: 'POST',
url: 'https://zoom.us/oauth/token?grant_type=client_credentials',
headers: {
/**The credential below is a sample base64 encoded credential. Replace it with "Authorization: 'Basic ' + Buffer.from(your_app_client_id + ':' + your_app_client_secret).toString('base64')"
**/
Authorization: 'Basic abcdsdkjfesjfg',
},
};
request(options, function (error, response, body) {
if (error) throw new Error(error);
console.log(body);
});

After you receive your access token, you can start using the Server-to-Server OAuth app access token to access Zoom APIs. If using Chatbots, you can use it for the Send Chatbot Messages API.

To learn more about how you can start using OAuth in your app, read the OAuth with Zoom guide.

Using JWT apps

A JSON Web Token (JWT) lets you to create tokens that provide secure data transmission using a compact JSON object. JWTs contain a signed payload that helps establish server-to-server authentication.

If only you or your Zoom account users will use your app, it is recommended that you use JWT authentication. To do this, register a JWT app in the Zoom App Marketplace. Use the token generated from the JWT app and start making API requests to the Zoom APIs.

To learn more about JWTs, read the JWT with Zoom guide.

API requests

All API requests must be made over HTTPS. The https://api.zoom.us/v2/ URL is the request base URL. The complete URL varies depending on the accessed resource.

For example, to get a user's details in your app, you must make an GET request to the https://api.zoom.us/v2/users/{userId} URL, where {userId} is ther user's ID or email address. If your app is registered in the Zoom App Marketplace as an account-level OAuth app, your app must have the user:read:admin scope in order to use the Get a user API.

Requests for JWT apps

You do not need scopes for JWT apps. Your JWT app will only have access to your Zoom account's information. To view a specific user's information, you must provide the user's userId or email address as the {userId} value in the API path. You can also use the me keyword instead of the userId value.

Example Node.js API request with the user ID for Account-level apps

var request = require('request');
var options = {
method: 'GET',
// A non-existing sample userId is used in the example below.
url: 'https://api.zoom.us/v2/users/sjkf1234',
headers: {
authorization: 'Bearer {yourtokenhere}', // Do not publish or share your token publicly.
},
};
request(options, function (error, response, body) {
if (error) throw new Error(error);
console.log(body);
});

Requests for OAuth apps

To get information about a user with a user-level OAuth app, the app must have the user:read scope. While the URL for the request is the same, the behavior of userId value is different from an account-level apps. Instead of providing a user's userId or email address, you must use the me keyword as the value of the userId path parameter. Otherwise, your app will receive an invalid token error.

Example Node.js API request with the user ID for User-level apps

var request = require('request');
var options = {
method: 'GET',
// Use the `me` keyword for the request below.
url: 'https://api.zoom.us/v2/users/me',
headers: {
authorization: 'Bearer {yourtokenhere}', // Do not publish or share your token with anyone.
},
};
request(options, function (error, response, body) {
if (error) throw new Error(error);
console.log(body);
});

Requests for Server-to-Server OAuth apps

Server-to-Server OAuth apps also use scopes. You wouldn't use the me keyword with this app type; you must provide a userId or email address. See Server-to-Server authentication for details.

The me keyword

You can use the me keyword in place of the userId keyword in any supported API call. When you use the me keyword, the API call uses the authenticated user's access token.

For example, to use the API to update a user's settings as the authenticated user, you would call the API with the /users/me/settings path, not the /users/{userId}/settings path.

Shared access permissions

Some users may have permissions to access (create, read, update, or delete) information associated with other users on Zoom accounts. For example, the Schedule Privilege enables users to assign other users on their account to schedule meetings on their behalf. A user that has been granted this privilege has access to schedule meetings for the other user. A user may also have a role that grants them access to other user information.

With shared access permissions, a user can choose whether your app can access the following information:

  1. Only information associated with them as the user that added the app (including others involved in that information, for example, a calendar invitation), or
  2. Both the information associated with them and the others that user is allowed to access (again, along with the others included in that information, such as a calendar invitation).

Item 2 refers to when a user authorizes your app to use their "shared access permissions" after they add or manage your app on their account. In the example above, the user can choose to share access permissions to schedule meetings for another user's account with your app. See Allowing Apps access to shared access permissions for details on the end user experience.

Handling errors

Your app does not need to do anything different for this access. Zoom handles this via the Authorization server.

The users that added your app can continue using your app to access their associated information without the need to take any action. If your app does not access or change information associated with a user other than the user who added it, then you should not receive additional errors.

Your app will receive an error if your app attempts to access or change information for a user other than the one who added the app and when the user who added the app:

  • Is not authorized to access or change the other user's information, or
  • Has not authorized your app to use shared access permissions.

In this case, your app will receive a 403 response with an "authenticated user has not permitted access to the targeted resource" error. This will occur after a request to any API, such as:

  • /v2/meetings/{meetingId}/**
  • /v2/users/{userId}/**
  • /v2/webinars/{webinarId}/**
  • /v2/**/recordings/
  • /v2/phone/** (user-level)

Currently, there is no way for your app to know whether a user has authorized shared access permissions for your app. You may be able to determine whether a user should have shared permissions based on the context. For example, your app lets users schedule meetings. In this case, when your app receives the error, you can point the user to the Allowing Apps access to shared access permissions Zoom Help Center article that describes how the user can authorize shared permissions for the app.

Once the user authorizes your app with shared permissions, the API will return the expected response.

Email address display rules

Zoom displays email addresses for users external to your account only if they meet any of the conditions below:

  • If the participant entered their email address into the meeting or webinar registration flow, then it will be shown for that specific meeting or webinar.
  • If the host provided the participant's email to Zoom in the following ways:
    • If the participant is on the calendar invitation or event using one of Zoom's calendar integrations (Outlook or Google Calendar).
    • If the participant has externally authenticated using an authentication system provided by the host.
    • If the participant email was entered with the "Allow authentication exception" option under "Only authenticated users can join..."
    • If the participant's email was entered using the Breakout Rooms assignment feature or "Allow authentication exception" to Breakout Rooms feature.
    • If you import a CSV file for panelists and attendees of a webinar.

For more information, read the "Zoom API email address display rules" Changelog post.

Understanding Personal Meeting ID (PMI)

You can start instant meetings and schedule meetings with your Personal Meeting ID (PMI). See the Zoom Support articles, Using Personal Meeting ID (PMI) and Personal meeting ID (PMI) and personal link, for details.

When Zoom creates a meeting using your PMI, it creates a unique meeting ID that you can see in the create meeting response. However, Webhooks events will still show your PMI. You should also use your PMI to pass into endpoints, such as:

Need help?

If you're looking for help, try Developer Support or our Developer Forum. Priority support is also available with Premier Developer Support plans.