How to create a JWT credential

Last updated: 2022-03-04 Contributors Byrne Reese
Edit this page

The JWT Auth flow is a secure and easy way for authenticating a user on the RingCentral platform. A JWT credential operates in the same way that a username and password do, in that:

  • An app presents a JWT credential to the Auth API.
  • The Auth API responds with an access token.
  • The app presents the access token in the Bearer HTTP header in subsequent calls to the API.

In this way, a JWT is not actually and directly associated with an application. JWT credentials belong to users, as users are the ones who authenticate and use the API. The user a JWT credential is associated with in turn determines what features and capabilities can be performed using that credential. For example, if a user Luke does not have permission to edit accounts, and Luke's credential is used to edit an account, then that API call will fail because Luke's account lacks the necessary permission.

Creating a JWT credential

JWT tokens are created exclusively within the RingCentral Developer Console. For this reason, JWT credentials can only be created by users who have a valid developer account or role. To create a JWT used for app authentication, follow these steps:

  1. Login to the RingCentral Developer Console. If you do not have access to the Developer Console, please reach out to your account administrator to request access.

  2. Hover your mouse over your name in the upper righthand corner, and select "Credentials."

  3. Click "Create JWT."

  4. Configure your JWT and click "Create."

Special considerations for Developer Admins

Developers with the role of "Developer Admin" have the ability to not only manage their own JWT credentials, but also the JWT credentials of other developers within their organization. To manage another developer's credentials, click on "Organization" in the navigation. Then select the developer whose credentials you would like to manage, and finally click on "Credentials" in the navigation.

How to restrict usage of a JWT to an specific application

For added security, especially when you intend to share your JWT with a third-party, we recommend you restrict your JWT to be used with a finite list of apps. To restrict a JWT to be used with only a specific app, you will need to ask the application developer for the client ID of their application.

Then check "Only specific apps of my choice" under "What apps are permitted to use this credential?" and copy and paste the client ID you received into the text field.

Click "Add app." If the app was found, a table will appear showing the current list of apps authorized to use this token.

Click "Create" or "Save."

Using JWT in sandbox versus production

JWT credentials are bound to the environment specified when they were created. A JWT configured for sandbox cannot be used to authenticate in production, and vice versa.

Furthermore, JWT credentials are owned by a specific individual. So, if a user does not have an account in their sandbox environment, they will be unable to generate a JWT in sandbox. To fix this problem, navigate to your sandbox accounts page and look for the section entitled, "Your login credentials." Click the create sandbox account link as instructed to create an account for yourself within the sandbox environment.