Set up to authenticate Nylas users with Zoom

In Nylas v3 and later, you can authenticate users with Zoom to automatically add Zoom conferencing information to events. This process uses OAuth, and requires you to create a free Zoom Marketplace application so you can authenticate with Zoom. (You don't need to make the Zoom application public.) You then create a conferencing connector in your Nylas application, and set up authentication values.

While the Zoom connector uses OAuth to authenticate users with the Zoom service, Zoom does not provide email or calendar services, and so you can't use the Nylas Email or Calendar APIs with it. You can only use the Zoom connector to generate conferencing details.

Create a Zoom OAuth application

First, create your Zoom OAuth application:

Make sure you're signed in with your Zoom account, then go to the Zoom App Marketplace.
From the Develop menu at the top-right, select Build app.
On the page that appears, locate and copy your client ID and client secret for the new Zoom app. Keep these in a secure location.
Optionally, click the pencil icon and enter a non-default name for your app.
Still on the Basic Information screen, scroll down to the OAuth information section.
- If you're using Nylas Hosted OAuth enter the redirect URL for your region:
  https://api.us.nylas.com/v3/connect/callback for the US region,
  https://api.eu.nylas.com/v3/connect/callback for the EU region.
  If you have Nylas applications in both regions, add one in the OAuth Redirect URL field, and the other in the allowlist further down the page.
- If you're using Custom auth, enter your custom redirect URL.
Click Scopes in the left navigation.
Click Add Scopes, and in the dialog that appears search for and select the following two scopes, then click Done.
- "Create a meeting for a user" - meeting:write:meeting
- "View a user" - user:read:user
Click Add App Now.

Make note of the the client ID and client secret that Zoom provides, and keep them somewhere safe. You’ll need them in the next step.

✅ 👀 You don't need to make your Zoom application public or publish it on the Zoom Marketplace, as long as you're authenticating users from within your own organization. If you plan to allow users from multiple domains to authenticate with Zoom, contact Zoom support for more details.

Create a Zoom conferencing connector

Create a Zoom connector either:
- From the v3 Dashboard: Click Connectors, click the plus sign next to Zoom, and on the next screen enter the Zoom Client ID and Zoom Client Secret received when you created your Zoom application.
- By API: Make a POST /v3/connectors request and include the client_id and client_secret you received when you created your Zoom application.
  Don't include default scopes when you create the connector.
(Optional) If you want to redirect users to a specific URL in your project after they authenticate with Zoom specifically, add that URL to your application.
You can do this either from the Nylas v3 Dashboard, or by making a POST /v3/applications/redirect-uris request.

Authenticate an existing user with Zoom

Next, authenticate an existing user with the Zoom service. The user you are authenticating with Zoom must have already authenticated successfully with Nylas, and have a valid grant ID before you proceed.

You can either use Nylas Hosted OAuth to authenticate with Zoom, or if you already have credentials from Zoom, you can use Nylas Custom authentication. See the v3 Authentication documentation for more information.

Connect to Zoom using Hosted OAuth

In the Hosted OAuth process, you start an authentication request with Zoom, and Zoom returns a verification code. You then exchange that code with Nylas to get the Zoom grant ID (conf_grant_id) for the user. You'll use that conf_grant_id in a Create event request to enable meeting autocreation.

Start Hosted OAuth with Zoom
Hosted OAuth Exchange Zoom token

https://api.us.nylas.com/v3/connect/auth?
  client_id=<NYLAS_CLIENT_ID>
  &redirect_uri=https://myapp.com/callback-handler  // Your application's callback_uri.
  &response_type=code
  &access_type=offline
  &provider=zoom

curl --request POST \
  --url 'https://api.us.nylas.com/v3/connect/token' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: <NYLAS_API_KEY>' \
  --data '{
      "code":"<NYLAS_CODE>",
      "client_id":"<NYLAS_CLIENT_ID>",
      "client_secret":"<NYLAS_API_KEY>",
      "redirect_uri":"http://myapp.example.com/callback",
      "grant_type":"authorization_code"
  }'

Connect to Zoom using Custom authentication

If you are using Custom auth with Zoom, follow the instructions in the official Zoom OAuth documentation to get a Zoom refresh_token. You include that Zoom refresh_token in a Custom authentication request.

Custom auth with Zoom

curl --request POST \
  --url 'https://api.us.nylas.com/v3/connect/custom' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: <NYLAS_API_KEY>' \
  --data '{
      "provider": "zoom",
      "settings": {
          "refresh_token": "<ZOOM_REFRESH_TOKEN>"
      }
  }'

Save the returned grant ID, as you'll use that as the conf_grant_id for that user.

Create a calendar event with autocreated conferencing

Next, create an event as usual, using the autocreate dict to pass the user's Zoom grant ID as conf_grant_id. Nylas contacts Zoom to create the conference, then creates the event.

If Nylas is unable to create the Zoom conference for any reason, it returns a 400 response and forwards the Zoom error message.

🔍 Good to know: Nylas uses the enum zoom when authenticating and creating a connector, and Zoom Meeting when autocreating a meeting.

Conferencing object with autocreate
Full cURL request

"conferencing": {
  "provider": "Zoom Meeting",
  "autocreate": {
        "conf_grant_id": "<USER_ZOOM_GRANT_ID>"
  }
}

curl --request POST \
  --url https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/events?calendar_id=<CALENDAR_ID> \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "title": "Philosophy Club Zoom Meeting",
    "status": "confirmed",
    "busy": true,
    "conferencing": 
    {
      "provider": "Zoom Meeting",
      "autocreate": 
      {
        "conf_grant_id": "<USER_ZOOM_GRANT_ID>" 
      }
    },
    "participants": [
      {
        "name": "Aristotle",
        "email": "aristotle@example.com"
      },
      {
        "name": "Jane Stephens",
        "email": "jane.stephens@example.com"
      }
    ],
    "description": "Come ready to talk philosophy!",
    "when": {
        "start_time": 1674604800,
        "end_time": 1722382420,
        "start_timezone": "America/New_York",
        "end_timezone": "America/New_York"
    }
}'

Zoom conferencing behavior and limitations

When you create or update an event with autocreated Zoom conferencing, Nylas first contacts the Zoom service to create or modify the conference. If Nylas is unable to update the Zoom event the entire update command fails and the parent event is not updated either.

If you update an event's time, timezone, duration, title, or description, Nylas updates those fields on the Zoom conference.

When you delete an event, Nylas deletes the provider event first, then contacts Zoom to delete the associated conference. If Nylas is unable to delete the conference, it returns an error code and the event is still deleted, but the orphaned Zoom conference persists.

If you create or modify an event so that it occurs in the past, Nylas can update the event on the provider, but Zoom cannot. Instead, Zoom schedules the conference for the time you made the update request.