S2S OAuth Starter App

This boilerplate app creates a functional starting point for building internal applications using Zoom's REST APIs without needing to handle authentication yourself. Add routes or update these starting points with authentication and token refresh already provided by the server.

Built with Express for the server, Redis for token storage, and Axios for requests, this app is designed as a starting point. To update or add new Zoom API endpoints, add Express routes in /routes/api (and import them in index.js).

Note: Zoom server-to-server tokens are scoped during the app creation workflow. Your app's permissions will reflect what you register when setting up the app.

Getting started

1. Create a server-to-server OAuth app Before cloning, set up your app and collect your credentials. For questions on this, reference the docs on creating a server-to-server app. Make sure you activate the app. Follow our set up documentation or this video for a more complete walk through.
2. Add scopes to your app. In your app's Scopes tab, add the following scopes: meeting:write:admin, recording:write:admin, report:read:admin, user:write:admin, webinar:write:admin . Note: If you add additional API routes to this starter, you may need to add the corresponding scopes.
3. Install and run Docker Desktop.
4. Clone this repo -- git clone git@github.com:zoom/server-to-server-oauth-starter-api.git.
5. Add environment variables. Add a .env file to the top level of the repository -- touch .env. Fill in the following values from your app. The project includes an example in .env.example

ZOOM_ACCOUNT_ID=
ZOOM_CLIENT_ID=
ZOOM_CLIENT_SECRET=

Usage

To run the project in development mode (with hot reloading):

docker-compose up dev

To run the project in production mode:

docker-compose up prod

The app will now be running in a docker container available to test at http://localhost:8080/api/...

Sending a request to your server's routes, you'll now be able to make requests to Zoom APIs. To test, open up a terminal or a tool like Postman and send a GET request to http://localhost:8080/api/users. If everything's set up, this will return a list of all the users on your account.

Your server now provides the following API Routes:

Users

• GET /api/users --> list users
• POST /api/users/add --> create users
• GET /api/users/:userId --> get a user
• GET /api/users/:userId/settings --> get user settings
• PATCH /api/users/:userId/settings --> update user settings
• PATCH /api/users/:userId --> update a user
• DELETE /api/users/:userId --> delete a user
• GET /api/users/:userId/meetings --> list meetings
• GET /api/users/:userId/webinars --> list webinars
• GET /api/users/:userId/recordings --> list all recordings

Meetings

• GET /api/meetings/:meetingId --> get a meeting
• POST /api/meetings/:userId --> create a meeting
• PATCH /api/meetings/:meetingId --> update a meeting
• DELETE /api/meetings/:meetingId --> delete a meeting
• GET /api/meetings/:meetingId/report/participants --> get meeting participant reports
• DELETE /api/meetings/:meetingId/recordings --> delete meeting recordings

Webinars

• GET /api/webinars/:webinarId --> get a webinar
• POST /api/webinars/:userId --> create a webinar
• DELETE /api/webinars/:webinarId --> delete a webinar
• PATCH /api/webinars/:webinarId --> update a webinar
• GET /api/webinars/:webinarId/registrants --> list webinar registrants
• PUT /api/webinars/:webinarId/registrants/status --> update registrant's status
• GET /api/webinars/:webinarId/report/participants --> get webinar participant reports
• POST /api/webinars/:webinarId/registrants --> add a webinar registrant

To stop your container, run the following:

docker stop <container_id> or docker-compose down

Adding new API routes

As a starting point, this app predefines API routes in /routes/api for Meetings, Webinars, and Users, and Reports. Add new routes or update existing ones with the Zoom APIs you are looking to use.

If you wanted to add endpoints for Dashboards, for example, create a new route by adding routes/api/dashboards.js using routes/api/meetings.js as a template:

// create a new file:
// routes/api/dashboards.js
const express = require("express");
const axios = require("axios");
const qs = require("query-string");

const errorHandler = require("../../utils/errorHandler");
const { ZOOM_API_BASE_URL } = require("../../constants");

const router = express.Router();

router.get("/metrics/meetings", async (req, res) => {
  const { headerConfig, params } = req;

  try {
    const request = await axios.get(
      `${ZOOM_API_BASE_URL}/metrics/meetings`,
      headerConfig
    );
    return res.json(request.data);
  } catch (err) {
    return errorHandler(err, res, `Error fetching list of meetings`);
  }
});

module.exports = router;

In index.js, import the new routes:

/**
 * Add API Routes w/ tokenCheck middleware
 */
app.use("/api/dashboards", tokenCheck, require("./routes/api/dashboards"));

Need help?

For help using this app or any of Zoom's APIs, head to our Developer Forum.

Documentation

• API Reference
• Build a Server-to-Server OAuth App
• How to create and use a Server to Server OAuth App (Video)
• OAuth docs