OAuth with Zoom

The Zoom API uses OAuth 2.0 to authenticate and authorize users to make requests. To set up access credentials and request scopes for your app, create an OAuth app on the Marketplace. Follow the Create an OAuth App guide for a full walkthrough.

OAuth2 endpoints are located at https://zoom.us/oauth/.

All Zoom OAuth and API endpoints must be called from the server side of your application. If called from the client side, CORS errors will be thrown.

Example without optional parameters:

https://zoom.us/oauth/authorize?response_type=code&client_id=7lstjK9NTyett_oeXtFiEQ&redirect_uri=https://yourapp.example.com

This URL is the same as the Install Button link on the Zoom App Marketplace.

If this is the first time that you are requesting authorization from a user, the user will be prompted by Zoom to authorize access for your app.

If authorized, the user will be redirected to the redirect_uri with the authorization code in the code query parameter.

https://yourapp.com/?code=obBEe8ewaL_KdyNjniT4KPd8ffDWt9fGB

Set the scopes for your app in the Zoom App Marketplace. See Set Scopes for details.

Preserving User State in Redirect URLs

To provide user context in your app installation, attach a state query parameter to the redirect_uri parameter of the install link. When the user is returned to your app, the state parameter will be included along with the authorization code.

Example: https://zoom.us/oauth/authorize?response_type=code&client_id=7lstjK9NTyett_oeXtFiEQ&redirect_uri=https://yourapp.com&state={userState}

This would redirect the user to: https://yourapp.com?state={userState}&code=obBEe8ewaL_KdyNjniT4KPd8ffDWt9fGB

Using Proof Key for Code Exchange (PKCE)

Zoom supports PKCE when requesting user tokens. This offers better security by enabling clients to use a code challenge and code exchange as part of the initial user authorization request. See rfc7636 for details.

To use this feature, send the code_challenge and optional code_challenge_method in the user authorization request. Then send the code_verifier in the access token request (step 2 below).

If Zoom verifies that the code_challenge and the code_verifier match, the token endpoint continues processing. If they do not match, you’ll receive an invalid_grant error.

Step 2: Request Access Token

Make a POST request to https://zoom.us/oauth/token with the following HTTP request headers and request body:

Request

Here’s an example of a request for the authorization code:

POST /oauth/token HTTP/1.1 
Host: zoom.us 
Authorization: Basic base64Encode(client_id:client_secret)
Content-Type: application/x-www-form-urlencoded

code=[CODE]&grant_type=authorization_code&code_verifier=[CODE VERIFIER]&state=[STATE]

Response

If successful, the response body will be a JSON representation of the user’s access token:

{
  "access_token": "eyJhbGciOiJIUzUxMiIsInYiOiIyLjAiLCJraWQiOiI8S0lEPiJ9.eyJ2ZXIiOiI2IiwiY2xpZW50SWQiOiI8Q2xpZW50X0lEPiIsImNvZGUiOiI8Q29kZT4iLCJpc3MiOiJ1cm46em9vbTpjb25uZWN0OmNsaWVudGlkOjxDbGllbnRfSUQ-IiwiYXV0aGVudGljYXRpb25JZCI6IjxBdXRoZW50aWNhdGlvbl9JRD4iLCJ1c2VySWQiOiI8VXNlcl9JRD4iLCJncm91cE51bWJlciI6MCwiYXVkIjoiaHR0cHM6Ly9vYXV0aC56b29tLnVzIiwiYWNjb3VudElkIjoiPEFjY291bnRfSUQ-IiwibmJmIjoxNTgwMTQ2OTkzLCJleHAiOjE1ODAxNTA1OTMsInRva2VuVHlwZSI6ImFjY2Vzc190b2tlbiIsImlhdCI6MTU4MDE0Njk5MywianRpIjoiPEpUST4iLCJ0b2xlcmFuY2VJZCI6MjV9.F9o_w7_lde4Jlmk_yspIlDc-6QGmVrCbe_6El-xrZehnMx7qyoZPUzyuNAKUKcHfbdZa6Q4QBSvpd6eIFXvjHw",
  "token_type": "bearer",
  "refresh_token": "eyJhbGciOiJIUzUxMiIsInYiOiIyLjAiLCJraWQiOiI8S0lEPiJ9.eyJ2ZXIiOiI2IiwiY2xpZW50SWQiOiI8Q2xpZW50X0lEPiIsImNvZGUiOiI8Q29kZT4iLCJpc3MiOiJ1cm46em9vbTpjb25uZWN0OmNsaWVudGlkOjxDbGllbnRfSUQ-IiwiYXV0aGVudGljYXRpb25JZCI6IjxBdXRoZW50aWNhdGlvbl9JRD4iLCJ1c2VySWQiOiI8VXNlcl9JRD4iLCJncm91cE51bWJlciI6MCwiYXVkIjoiaHR0cHM6Ly9vYXV0aC56b29tLnVzIiwiYWNjb3VudElkIjoiPEFjY291bnRfSUQ-IiwibmJmIjoxNTgwMTQ2OTkzLCJleHAiOjIwNTMxODY5OTMsInRva2VuVHlwZSI6InJlZnJlc2hfdG9rZW4iLCJpYXQiOjE1ODAxNDY5OTMsImp0aSI6IjxKVEk-IiwidG9sZXJhbmNlSWQiOjI1fQ.Xcn_1i_tE6n-wy6_-3JZArIEbiP4AS3paSD0hzb0OZwvYSf-iebQBr0Nucupe57HUDB5NfR9VuyvQ3b74qZAfA",
  "expires_in": 3599,
  "scope": "user:read:admin"
}

This access token can now be used to make requests to the Zoom API. Access tokens expire after 1 hour.

Request:

Here’s an example request for a refresh token:

POST /oauth/token HTTP/1.1 
Host: zoom.us 
Authorization: Basic base64Encode(client_id:client_secret)
Content-Type: application/x-www-form-urlencoded

refresh_token=[REFRESH TOKEN]&grant_type=refresh_token

Response

If successful, the response body will be a JSON representation of your user’s refreshed access token:

{
    "access_token": "eyJhbGciOiJIUzUxMiIsInYiOiIyLjAiLCJraWQiOiI8S0lEPiJ9.eyJ2ZXIiOiI2IiwiY2xpZW50SWQiOiI8Q2xpZW50X0lEPiIsImNvZGUiOiI8Q29kZT4iLCJpc3MiOiJ1cm46em9vbTpjb25uZWN0OmNsaWVudGlkOjxDbGllbnRfSUQ-IiwiYXV0aGVudGljYXRpb25JZCI6IjxBdXRoZW50aWNhdGlvbl9JRD4iLCJ1c2VySWQiOiI8VXNlcl9JRD4iLCJncm91cE51bWJlciI6MCwiYXVkIjoiaHR0cHM6Ly9vYXV0aC56b29tLnVzIiwiYWNjb3VudElkIjoiPEFjY291bnRfSUQ-IiwibmJmIjoxNTgwMTQ3Mzk0LCJleHAiOjE1ODAxNTA5OTQsInRva2VuVHlwZSI6ImFjY2Vzc190b2tlbiIsImlhdCI6MTU4MDE0NzM5NCwianRpIjoiPEpUST4iLCJ0b2xlcmFuY2VJZCI6MjZ9.5c58p0PflZJdlz4Y7PgMIVCrQpHDnbM565iCKlrtajZ5HHmy00P5FCcoMwHb9LxjsUgbJ7653EfdeX5NEm6RoA",
    "token_type": "bearer",
    "refresh_token": "eyJhbGciOiJIUzUxMiIsInYiOiIyLjAiLCJraWQiOiI8S0lEPiJ9.eyJ2ZXIiOiI2IiwiY2xpZW50SWQiOiI8Q2xpZW50X0lEPiIsImNvZGUiOiI8Q29kZT4iLCJpc3MiOiJ1cm46em9vbTpjb25uZWN0OmNsaWVudGlkOjxDbGllbnRfSUQ-IiwiYXV0aGVudGljYXRpb25JZCI6IjxBdXRoZW50aWNhdGlvbl9JRD4iLCJ1c2VySWQiOiI8VXNlcl9JRD4iLCJncm91cE51bWJlciI6MCwiYXVkIjoiaHR0cHM6Ly9vYXV0aC56b29tLnVzIiwiYWNjb3VudElkIjoiPEFjY291bnRfSUQ-IiwibmJmIjoxNTgwMTQ3Mzk0LCJleHAiOjIwNTMxODczOTQsInRva2VuVHlwZSI6InJlZnJlc2hfdG9rZW4iLCJpYXQiOjE1ODAxNDczOTQsImp0aSI6IjxKVEk-IiwidG9sZXJhbmNlSWQiOjI2fQ.DwuqOzywRrQO2a6yp0K_6V-hR_i_mOB62flkr0_NfFdYsSqahIRRGk1GlUTQnFzHd896XDKf_FnSSvoJg_tzuQ",
    "expires_in": 3599,
    "scope": "user:read"
}

Refresh tokens expire after 15 years. The latest refresh token must always be used for the next refresh request.

Request:

Here’s an example request to revoke an access token:

POST /oauth/revoke HTTP/1.1 
Host: zoom.us 
Authorization: Basic base64Encode(client_id:client_secret)
Content-Type: application/x-www-form-urlencoded; charset=UTF-8 4

token=[ACCESS TOKEN]

Response

If successful, the response body will be a JSON success object:

{
  "status": "success"
}

Example:

https://zoom.us/oauth/authorize?response_type=code&client_id=U1RqQ9UsQo6hd6fJQWFLQ&redirect_uri=https://yourapp.com

This URL is the same as the Install Button link on the Zoom App Marketplace.

If this is the first time that you are requesting authorization from a user, the user will be prompted by Zoom to authorize access for your app.

If authorized, the user will be redirected to the redirect_uri with the authorization code in the code query parameter.

https://yourapp.com/?code=obBEe8ewaL_KdyNjniT4KPd8ffDWt9fGB

Notice the code returned in the redirect URL. Follow Step 2 in Requesting an Access Token to obtain an OAuth Access Token.

To get a Chatbot token, make a POST request to https://zoom.us/oauth/token with the following query parameters and authorization header:

Example Request:

POST

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

Request Headers:

{
  "Authorization": "Basic Q2xpZW50X0lEOkNsaWVudF9TZWNyZXQ="
}

If successful, the response body will be a JSON representation of the Chatbot token:

{
  "access_token": "eyJhbGciOiJIUzUxMiIsInYiOiIyLjAiLCJraWQiOiI8S0lEPiJ9.eyJhdWQiOiJodHRwczovL29hdXRoLnpvb20udXMiLCJ2ZXIiOiI2IiwibmJmIjoxNTgwMTQ2NjkzLCJjbGllbnRJZCI6IjxDbGllbnRfSUQ-IiwiaXNzIjoidXJuOnpvb206Y29ubmVjdDpjbGllbnRpZDo8Q2xpZW50X0lEPiIsImF1dGhlbnRpY2F0aW9uSWQiOiI8QXV0aGVudGljYXRpb25fSUQ-IiwiZXhwIjoxNTgwMTUwMjkzLCJ0b2tlblR5cGUiOiJjbGllbnRfdG9rZW4iLCJpYXQiOjE1ODAxNDY2OTMsInVzZXJJZCI6IjxVc2VyX0lEPiIsImdyb3VwTnVtYmVyIjowLCJqdGkiOiI8SlRJPiJ9.chgzEaGxeYl3alAaLsFSRvQFVRqoabM5BINVELOYPO1FqveoEk02i8AIGrtg0FiX779pMWpMObkxFnPQy7euNA",
  "token_type": "bearer",
  "expires_in": 3599,
  "scope": "imchat:bot"
}

Chatbot tokens expire after one hour.

Using a Chatbot Token

Make requests to the Chatbot API by sending the Chatbot token as the Authorization Bearer header:

"Authorization": "Bearer <CHATBOT_TOKEN>"

Example Request:

POST

https://api.zoom.us/v2/im/chat/messages

Request Headers

{
  "Authorization": "Bearer eyJhbGciOiJIUzUxMiIsInYiOiIyLjAiLCJraWQiOiI8S0lEPiJ9.eyJhdWQiOiJodHRwczovL29hdXRoLnpvb20udXMiLCJ2ZXIiOiI2IiwibmJmIjoxNTgwMTQ2NjkzLCJjbGllbnRJZCI6IjxDbGllbnRfSUQ-IiwiaXNzIjoidXJuOnpvb206Y29ubmVjdDpjbGllbnRpZDo8Q2xpZW50X0lEPiIsImF1dGhlbnRpY2F0aW9uSWQiOiI8QXV0aGVudGljYXRpb25fSUQ-IiwiZXhwIjoxNTgwMTUwMjkzLCJ0b2tlblR5cGUiOiJjbGllbnRfdG9rZW4iLCJpYXQiOjE1ODAxNDY2OTMsInVzZXJJZCI6IjxVc2VyX0lEPiIsImdyb3VwTnVtYmVyIjowLCJqdGkiOiI8SlRJPiJ9.chgzEaGxeYl3alAaLsFSRvQFVRqoabM5BINVELOYPO1FqveoEk02i8AIGrtg0FiX779pMWpMObkxFnPQy7euNA"
}

Request Body:

{
  "robot_jid": "v1zx6cy00psoylshypvg-iuq@xmpp.zoom.us",
  "to_jid": "kdykjnimt4kpd8kkdqt9fq@xmpp.zoom.us",
  "account_id": "gVcjZnWWRLWvv_GtyGuaxg",
  "content": {
    "head": {
      "text": "Hello World"
    }
  }
}

If successful, the response body will be a JSON representation of the sent Chatbot message:

{
	"message_id": "20191218175454248_UvRlxOz_aw1",
	"robot_jid": "v1zx6cy00psoylshypvg-iuq@xmpp.zoom.us",
	"sent_time": "2019-12-18 17:54:54",
	"to_jid": "kdykjnimt4kpd8kkdqt9fq@xmpp.zoom.us"
}

Refreshing a Chatbot Token

Refreshing a Chatbot token is the same process as requesting a Chatbot token. Make a POST request to https://zoom.us/oauth/token with the following query parameters and authorization header:

Example Request:

POST

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

Request Headers:

{
  "Authorization": "Basic Q2xpZW50X0lEOkNsaWVudF9TZWNyZXQ="
}

If successful, the response body will be a JSON representation of your refreshed Chatbot token:

{
  "access_token": "eyJhbGciOiJIUzUxMiIsInYiOiIyLjAiLCJraWQiOiI8S0lEPiJ9.eyJhdWQiOiJodHRwczovL29hdXRoLnpvb20udXMiLCJ2ZXIiOiI2IiwibmJmIjoxNTgwMTQ2NjkzLCJjbGllbnRJZCI6IjxDbGllbnRfSUQ-IiwiaXNzIjoidXJuOnpvb206Y29ubmVjdDpjbGllbnRpZDo8Q2xpZW50X0lEPiIsImF1dGhlbnRpY2F0aW9uSWQiOiI8QXV0aGVudGljYXRpb25fSUQ-IiwiZXhwIjoxNTgwMTUwMjkzLCJ0b2tlblR5cGUiOiJjbGllbnRfdG9rZW4iLCJpYXQiOjE1ODAxNDY2OTMsInVzZXJJZCI6IjxVc2VyX0lEPiIsImdyb3VwTnVtYmVyIjowLCJqdGkiOiI8SlRJPiJ9.chgzEaGxeYl3alAaLsFSRvQFVRqoabM5BINVELOYPO1FqveoEk02i8AIGrtg0FiX779pMWpMObkxFnPQy7euNA",
  "token_type": "bearer",
  "expires_in": 3599,
  "scope": "imchat:bot"
}

Chatbot tokens expire after one hour.