JWT app type migration guide

If you use a JWT app type in your account, you should consider switching to using a Server-to-Server OAuth or OAuth app type, depending on your use case. This document will help guide you to migrate to one of those app types.

On this page

Overview

A JavaScript Object Notation (JSON) Web Token, abbreviated JWT, is a compact, URL-safe way of representing information (claims) to transfer between parties. See RFC 7519 for details.

Zoom provided a JWT app type to enable Developers to create apps that could use all of the permissions of an administrator of a Zoom account. Developers could use the API Key and Secret to generate a JWT for use in their integrations. An account could only have one JWT app and it could be used to authenticate and authorize the permissions for any number of account integrations.

Integrations using a JWT for authentication and authorization did not need to get end user permission for the data they could access. The wide scope of access provided by the JWT app type is not optimal when compared to the diversity of scopes offered by OAuth apps. Additionally, if an account Administrator or Developer needed to regenerate the JWT API Secret, they would have to re-authenticate all of the other integrations that used it.

For these reasons and others, Zoom will deprecate the JWT app type in June, 2023.

JWT app type to OAuth app type migration

If you have an existing JWT app, the Create page on the App Marketplace indicates that “Your account already has JWT credentials,” as shown below:

app types showing existing JWT app type

Depending on your use case, you should switch your integrations to use the credentials offered by a Server-to-Server OAuth or OAuth app type. Consider the following when determining which app type to use:

  • Server-to-Server OAuth app type. Use this app type if your integration is an internal app, only available to users in my account, and you don’t need users to authorize access to their data to use it. This app type uses an account-level access token. Use this app type for users created with custCreate.

  • OAuth app type. Use this app type if your integration is an app installed by users on your account or other accounts, for example, if you’re going to share your integration externally on the Zoom App Marketplace. This app type uses a user-level access token.

See Using OAuth 2.0 to see the workflows for user-authenticated (OAuth) and Server-to-Server authentication, how to generate an OAuth token, and how to make API calls using it.

JWT app type to SDK app type migration

In the past, the Meeting SDK for Web required a Zoom JWT app type to generate the SDK Auth signature. Now the Meeting SDK for Web can use the Zoom SDK app type to generate the SDK Auth signature. The Zoom SDK app type also includes OAuth functionality which allows you to start meetings on a Zoom user's behalf.

Migration guide for Meeting SDK for Web using a Zoom JWT app type

In the Meeting SDK for Web version 2.7.0 releasing at the end of August 2022, the apiKey property will be removed from the join() function.

If you plan to upgrade to version 2.7.0, but are still using the apiKey property, you must use the sdkKey property (available since version 2.3.0) and pass in your SDK app type SDK Key instead of the JWT app type API Key.

You must also update your SDK signature logic to use the SDK JWT Auth format. See the Detailed steps to complete the migration for details on this process.

Detailed steps to complete the migration

  1. Create an SDK app type if you do not already have one.

    Meeting SDK Create SDK app
    • If you already have an SDK app type, and it has an "Update" flag, click "Update". This will not break your SDK app’s functionality. It simply adds Zoom User Level OAuth capabilities to your SDK app which is optional for you to use.

      Meeting SDK Update SDK app
    • To list your app on the Zoom App Marketplace for other Zoom users outside your account to use, toggle the switch under "Would you like to publish this app on Zoom App Marketplace?" Note that choosing this option will not publish your app right away, you will have to go through the publication publication process first. See Publishing an app for details.

      Meeting SDK Update SDK app Options
  2. In your SDK app type, on the App Credentials page, copy the SDK Key, you will need it for the next step.

    Meeting SDK app SDK Key
  3. In your Meeting SDK for Web code, update the join() function object to use the key: sdkKey instead of the key: apiKey. Set the value of the sdkKey to your SDK Key from step 2.

    Meeting SDK Client View join function
    Meeting SDK Component View join function
  4. Update your signature generation logic to use the SDK JWT Auth format.

    • Pass the updated signature format to the same signature property value that you have been using.
    • See the SDK JWT Auth Sample App (Node.js) for an example.
    • Error Code 3 means you are still using the apiKey.
      Meeting SDK API Key Error

JWT app type vs Server-to-Server OAuth app types

The Server-to-server OAuth app overcomes the following limitations of the JWT app:

  • You can restrict the permissions on the token by providing scopes through the app.
  • The token has a set expiration time of one hour (3600 seconds).
  • You can create multiple Server-to-server OAuth apps in your account.

Access to scopes

The administrator for a Zoom account must enable the View and Edit permissions for Server-to-Server OAuth app. This is described on the Create a Server-to-Server OAuth app page, but it’s also applicable to the OAuth app type.

Using the Server-to-Server OAuth app, a Developer can generate access tokens without requiring user Authorization. Therefore, a Developer can only see the scopes that they are able to authorize. If a Developer needs access to additional scopes, the account administrator must give their role additional access permissions. See Using role management for details.

When choosing scopes for an OAuth app type, be sure to choose all of the scopes that you need as if you need to add more later, the user will have to re-authorize the app.

Removing access to an app or token

Server-to-Server OAuth tokens expire 60 minutes after generation. Once expired, you can generate new tokens using the API credentials. You should not share your credentials outside of your account. If you feel that your credentials are compromised you can do any of the following:

  • Regenerate the client secret. This invalidates the previous key and tokens.
  • Go to your app, choose Activation, and Deactivate your app. Doing so will restrict users from generating the tokens from this app.
  • Go to Created apps in the Marketplace and choose the action Remove app. This invalidates the existing app credentials and tokens.

Need help?

If you're looking for help, try Developer Support or our Developer Forum. Priority support is also available with Premier Developer Support plans.