Introduction
Using Zoom APIs
Pagination
Error Definitions
Rate Limits
Testing Zoom APIs
Accounts
Billing
Chat Channels
Chat Messages
Contacts
Cloud Recording
Dashboards
Devices
Groups
IM Chat
IM Groups
Meetings
PAC
Phone
Reports
Roles
Rooms
SIP Phone
TrackingField
TSP
Users
Webinars
Account Events
App Events
Meeting Events
Recording Events
User Events
Webinar Events
Zoom Room Events
Data Compliance

Using Zoom APIs


Zoom APIs allow developers to request information from the Zoom including but not limited to User details, Meeting reports, Dashboard data, etc. as well as perform actions on the Zoom platform on a user’s behalf, such as, creating a new user or deleting meeting recordings.

Authentication

Every HTTP request made to Zoom API must be authenticated by Zoom. Zoom supports the following two primary means for request authentication:

  1. OAuth 2.0
  2. JWT

Using OAuth 2.0

OAuth 2.0 allows applications to obtain access to Zoom resources (such as the user’s profile information) that are made available via the Zoom API.

The following sections will provide an overview on the OAuth protocol. To start using the OAuth protocol for your app’s authentication with Zoom, you must first create an OAuth app in the Zoom App Marketplace. To see a sample OAuth app in action, checkout the Quickstart - OAuth guide.

OAuth Roles

The OAuth protocol defines four specific roles and these roles are actively involved in the process of authentication flow with Zoom APIs:

  • Resource Owner: The resource owner is 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: Resource Server is the server that is hosting the resource. If your application is integrating with the Zoom API to obtain user-related information, the Zoom API server is considered the resource server.

  • Client: The Client is the application that requests access to the user’s information. If your app makes access requests to the Zoom API, your app is considered as the Client.

Note: In this document, you will see the term “Client” and “app” being used interchangeably. Both of these terms refer to the app that needs to integrate with the Zoom APIs.

Generally, the interaction between a Client (your app), a Zoom user, Zoom’s Authorization service and the Zoom API will look similar to the flow shown in the image below:

  1. The Client (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.
    An access token is a credential in the form of string that represents the authorization granted to the app. It can be compared with that of an ID card that identifies a person with their level of authority (such as a person’s driving license indicates that the person is authorized to drive).
  1. 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.

  2. 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.

OAuth Grant Types

An authorization grant represents the authorization assigned to the Client by the resource owner. The term “grant type” refers to the method that is used by the Client to request authorization. OAuth 2.0 supports various grant types. However, with Zoom APIs, you should use one of the following grant types where applicable:

Authorization Code

This 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 give you an overview of the Authorization Code Grant flow:

  1. The Client directs the user to the Zoom Authorization Server where the user sees a dialog box with permission request for access. This process is provisioned by Zoom via the Publishable URL. When a user tries to install your app or re-install 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:
  1. User authorizes or declines the app’s request.

  2. If user authorizes the request, 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 will look similar to this: https://yourapp’sredirecturlhere/?code={someauthorizationcode}.

  3. The Client makes a request to Zoom to exchange the authorization code for an access token.
Example
var request = require("request");

var options = {
  method: 'POST',
  url: 'https://api.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.ngrok.io'
  },
  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 access token for APIs that do not need a user’s permission, but rather a service’s permission. Within the realm of Zoom APIs, Client Credentials grant should be used to get access token from the Chatbot Service in order to use the Send Chatbot Messages API.

To use Client Credentials grant type, follow the steps listed below:

  1. Visit your App’s Dashboard on the Zoom App Marketplace.

  2. From the App Credentials page, copy the Client ID and Client Secret of your app.
  1. Make a POST request to the Zoom Authorization Endpoint URL: https://api.zoom.us/oauth/token?grant_type=client_credentials . The value of the query parameter grant_type is set as “client_credentials” to indicate the Client Credentials grant type.
    Use Basic access authentication header and provide base64 encoded string of your Client ID and Client Secret as credentials.

    An example of this request is shown below:
Example
var request = require("request");

var options = {
  method: 'POST',
  url: 'https://api.zoom.us/oauth/token',
  qs: {
   grant_type: 'authorization_code',
   code: 'BiwC4Ob5pS_z8yCxjjyTSiw02QgCfp8uQ',
   redirect_uri: 'https://87bdba72.ngrok.io'
  },
  headers: {
   Authorization: 'Basic abcdsdkjfesjfg'
  };

  request(options, function(error, response, body) {
   if (error) throw new Error(error);

   console.log(body);
  });

After receiving the access token, you can start using the Send Chatbot Messages API.

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

Using JWT

JSON Web Token (JWT) offer a method to generate tokens that provide secure data transmission using a neat and compact JSON object. JWTs contain signed payload that helps establish server to server authentication.

If your app is meant to be used only by yourself or by users that are in your Zoom account, it is recommended that you use JWT for 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 JWT, read the JWT with Zoom guide, followed by the Quickstart - JWT tutorial.

API Requests

All API requests must be made over HTTPS. The base URL for the request is https://api.zoom.us/v2/. The complete URL varies depending on the resource being accessed.
For instance, to get details about a specific user in your app, you must make an HTTP GET request to this URL: https://api.zoom.us/v2/users/{userId}. If your app is registered as an account-level OAuth app in the Marketplace, your app must have the user:read:admin scope in order to use the Get a Specific User API.

If your app is a JWT app, no scopes are needed as your app will only have access to information within your Zoom account. In both of these cases, provide the actual userId or email address of the user whose details you would like to view as the value of the userId path parameter. Optionally, you can also use the me keyword as the value of the userId which represents the authenticated user.

Example
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);
});

For a user-level OAuth app to get details about a specific user, the app must have user:read scope. Although the URL for the request is the same, the behavior of userId differs from that of account-level apps. Instead of providing the “userId” or email address of a user, you must provide the “me” keyword as the value of the userId path parameter. Otherwise, your app will receive an invalid token error.

Example
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);
});

Need Support?

The first place to look for help is on our Developer Forum, where Zoom Marketplace Developers can ask questions for public answers.

If you can’t find the answer in the Developer Forum or your request requires sensitive information to be relayed, please email us at developersupport@zoom.us.