Authorization


To interact with Zoom, Chatbot applications must be authorized in order to access resources and make requests. Different from other Marketplace apps, Chatbots authorize at the application level by requesting access tokens with a specific access grant type.

Access Tokens

Chatbots make requests as an application, and authorize using the OAuth2 grant type client_credentials. This differs from User-managed OAuth2 apps, which validate the User to make requests with the grant type code.

This means Chatbot apps only need to store and refresh one access_token for all Users.

Request an Access Token

To get a Chatbot access_token, make a POST request to the /oauth/token endpoint. This request must include your Client ID and Client Secret, which are found in your App Dashboard. For more information on generating or finding these credentials, see our Build a Chatbot App reference.

Example Request

POST https://api.zoom.us/oauth/token?grant_type=client_credentials

Request Details:

Path Params Description
grant_type Specifies who is making requests to the API, use client_credentials
Headers Description
authorization Basic base64Encode({client_id}:{client_sceret}) Client ID and Client Secret are found in the App Dashboard; Base64 encoded. Note: ClientID and Client Secret need to be separated by a colon.

Example Successful Response

{
  "access_token": "eyJhbGciOiJIUzUxMiJ9.eyJhdWQiOiJodHRwczovL29hdXRoLnp",
  "token_type": "bearer",
  "expires_in": 3599,
  "scope": "imchat:bot"
}

Refresh Access Token

Each access_token is valid for one hour. To refresh the token, simply make another request to the same /oauth/token endpoint with the same credentials to receive a new access_token.

Note: Unlike User-managed OAuth2 apps, Chatbots do not use separate access and refresh tokens. One token, the access token, is refreshed after expiration.

When sending Chatbot messages, the access_token must be included in the request header as described in our Sending Messages reference.

"Authorization": "Bearer {{access_token}}"

Installation

Chatbot apps can be distributed and installed on the Zoom Client in one of three ways: during development for local testing, unlisted for private use, or publicly on the Zoom App Marketplace. Each option requires additional information or approval.

Local Testing

Chatbot apps can be installed on your Zoom account during development for local testing. Apps in development can only be distributed and installed by Users on your Zoom account, and require development stage credentials and Redirect URL.

Unlisted

For private Chatbot apps or those which are not intended to be published publicly on the Zoom Marketplace, Users on your account can install a production version of your Chatbot app through a Publishable URL or embeddable button.

With specific permission from Zoom, a shareable link may be requested to install your Chatbot app for Users outside of your account.

Publicly on the Zoom App Marketplace

Chatbot apps may be listed on the Zoom App Marketplace to be installed publicly by any Zoom User. To submit a Chatbot app for approval, follow the specific steps on the Submission Checklist, along with validating a domain, adding release notes, supplying test account credentials, and accepting the Zoom Marketplace Developer Agreement. For a more thorough guide to Chatbot app submission, follow the requirements on the Build a Chatbot App guide, or reference our App Lifecycle Management guide.

Deauthorization

When a User uninstalls a production Chatbot app, an HTTP POST request will be sent to the Chatbot’s Deauthorization Notification Endpoint URL specified in the App Dashboard’s Features page. For more information on this URL, reference our Build a Chatbot App guide.

It is highly recommended all Chatbot apps verify the Authorization code contained in the header of this request before performing Deauthorization. Unsecured Deauthorization Notification Endpoint URLs will leave the Chatbot app vulnerable to denial of service attacks.

After receiving a Deauthorization request, Chatbot apps must delete all associated User data and notify Zoom of the action by sending an HTTP POST request to the Data Compliance API. For a full reference on Deauthorization, reference our Data Compliance guide.

Below is an example Deauthorization request body, sent to the Chatbot’s Deauthorization Notification Endpoint URL:

{
  "event": "app_deauthorized",
  "payload": {
    "user_data_retention": "false",
    "account_id": "EabCDEFghiLHMA",
    "user_id": "z9jkdsfsdfjhdkfjQ",
    "signature": "827edc3452044f0bc86bdd5684afb7d1e6becfa1a767f24df1b287853cf73000",
    "deauthorization_time": "2019-06-17T13:52:28.632Z",
    "client_id": "ADZ9k9bTWmGUoUbECUKU_a"
  }
}

After receiving the Deauthorization request body, set the payload object of the request as the deauthorization_event_received object for the POST request sent to the Data Compliance API.

POST https://api.zoom.us/oauth/data/compliance

Example Request

Request Header:

{
  "Authorization": "Basic aWFtYWNsaWVudGlkOmlhbWFzZWNyZXRpZA==",
  "Content-Type": "application/json",
  "cache-control": "no-cache"
}

Request Body:

{
  "client_id": "ABcDefGHIj12A",
  "user_id": "a8yBxjayaSiw02igC8p8l0",
  "account_id": "abcdEfghIJklMn00",
  "deauthorization_event_received": {
    "user_data_retention": "false",
    "account_id": "EabCDEFghiLHMA",
    "user_id": "z9jkdsfsdfjhdkfjQ",
    "signature": "827edc3452044f0bc86bdd5684afb7d1e6becfa1a767f24df1b287853cf73000",
    "deauthorization_time": "2019-06-17T13:52:28.632Z",
    "client_id": "ADZ9k9bTWmGUoUbECUKU_a"
  },
  "compliance_completed": true
}

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.