JWT authorization code flow
New to JWT authentication? Checkout our getting started guide.
RingCentral supports RFC 7523 for using JSON Web Tokens ("JWT", pronounced "JAW-t") in an OAuth authorization flow. A JWT credential can be generated within the RingCentral Developer Console, and be used in place of a username and password when establishing an authenticated connection to RingCentral servers to call the API. Using a JWT in this way has the following benefits:
- Credentials do not expire (unless you elect otherwise)
- Credentials are persistent and cannot be changed once generated
- Credentials can be easily revoked by the owner or administrator
- Credentials can be restricted to specific applications
At a high-level, the JWT auth flow is as follows:
}
For a deeper dive of this flow, see "Technical discussion" below.
When should I use a JWT for authentication?
Using a JSON Web Token for app authentication is ideal in the following circumstances:
- You have a script or application with no user interface through which to facilitate the OAuth auth token flow.
- You need a way for users to grant access to their account using a credential that doesn't expire.
- You need a way to access an account that doesn't rely on token refreshing.
JWT versus Password-based authentication
RingCentral strongly recommends that developers utilize JWT for server-to-server authentication, as password-based authentication is considered less-secure. In addition, JWT authentication is compatible with far more applications. The table below describes the differences between these two authentication methods.
| Password-based | JWT-based | |
|---|---|---|
| Persistent and immutable | No | Yes |
| Compatible with accounts configured for Single Sign-on? | No | Yes |
| Compatible with private apps? | Yes | Yes |
| Compatible with public apps? | No | Yes |
How do I configure an app to use JWT authentication?
To use a JWT, the app you wish to present your JWT credentials to must first be configured to accept JWT tokens as a means of authentication.
How do I generate a JWT credential used for authentication?
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 the instructions below:
How does JWT authentication work?
JWT authentication and password-based authentication modes are almost identical. They both are a standards-compliant OAuth flow for which developers will perform the following steps:
- The developer presents a JSON Web Token to the platform.
- The platform responds with an access token.
- The developer utilizes the access token in subsequent requests to the API.
The key to groking how RingCentral uses JWTs is in understanding that JWTs are not used directly to call the API. Instead, a JWT is used in the process of obtaining an access token which is itself then used to call the API.
To learn more, see "Technical discussion" below.
Do JWTs expire or do they need to be refreshed?
While JWTs can be configured to never expire, the access tokens obtained via a JWT will always expire unless they are properly refreshed. However, unlike the traditional auth token flow in which a user must re-enter their username and password in order for the application to obtain a new access token, a JWT can easily be presented to the platform again in order to obtain a new and fresh access token.
In other words, JWTs are a way developers can obtain more reliable access to a user's account for the purposes of calling the API on their behalf. And in the event that an access token expires, a new one can be quickly generated without the need for a human to re-enter their login credentials.
JWT credentials and rate limiting
JWT credentials are used to obtain an access token by calling the Auth API, and are therefore subject to the same rate limits as any other means of authentication/authorization. To avoid being throttled by a rate limit, developers should re-use the access token they obtain until an appropriate time to dispose of it.
Technical discussion
JSON web tokens, or JWTs are a form of user credential that can be presented in RingCentral's OAuth flow to obtain an access token. There is only one call to make in JWT authentication: the call to request an access token. This call is described below.
Auth URLs
| Environment | Value |
|---|---|
| Sandbox | https://platform.devtest.ringcentral.com/restapi/oauth/token |
| Production | https://platform.ringcentral.com/restapi/oauth/token |
HTTP Headers
| Header | Value |
|---|---|
Content-type |
application/x-www-form-urlencoded |
Authorization |
Basic + base64_encoded( Client ID + ":" + Client Secret ) |
POST Body
| Parameter | Type | Description |
|---|---|---|
grant_type |
string | Required. Must be set to urn:ietf:params:oauth:grant-type:jwt-bearer. |
assertion |
string | Required. Provide your JWT token. |
Sample Request
POST /restapi/oauth/token HTTP/1.1
Accept: application/json
Content-Type: application/x-www-form-urlencoded
Authorization: Basic cmVsLWFsbC1wZXJtaXNzaWXFjMmpRZmlQcnlkSUkweE92QQ==
grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer
&assertion=eyJhbGciOiJFUzI1NiIsIm.eyJpc3Mi[...omitted for brevity...]
Sample Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"access_token" : "U1BCMDFUMDRKV1MwMXxzLFSvXdw5PHMsVLEn_MrtcyxUsw",
"token_type" : "bearer",
"expires_in" : 7199,
"refresh_token" : "U1BCMDFUMDRKV1MwMXxzLFL4ec6A0XMsUv9wLriecyxS_w",
"refresh_token_expires_in" : 604799,
"scope" : "AccountInfo CallLog ExtensionInfo Messages SMS",
"owner_id" : "256440016"
}