Password auth flow
Password grant type is deprecated
Starting in 2023, RingCentral will begin a careful and deliberative process of removing support for the username/password auth flow on the Platform. As a result, all developers are strongly encouraged to migrate their applications to JWT.
Please use the JWT auth flow
In January 2022, RingCentral released a more secure alternative to the password grant type called "JWT." We recommend all developers use the JWT flow going forward as eventually the password auth flow will be deprecated.
The password-based authorization flow is among the simplest OAuth 2.0 authorization flows to implement. It is suitable mostly for apps that both lack a user interface, and/or that use a single set of credentials to act on behalf of everyone within an account.
This authorization flow presumes you are in possession of a user's login credentials. If so, then obtaining an access token is a two-step process:
-
The application requests and access token by presenting a user's login credentials to the platform..
-
Once the credentials are successfully verified, the platform responds with the access and refresh tokens.
Below find the step-by-step instructions on how to perform two-legged authorization using the RingCentral API.
When should I use the password auth flow?
The password auth flow is used most often by apps that lack a frontend user interface, such as a script, cronjob, etc.
We recommend using the JWT authorization flow
The password grant flow for OAuth is discouraged as it requires developers to store username and password information on their servers, which if compromised, would give others full access to their account. A safer and recommended form of authentication is the JWT auth flow.
Password auth flow does not work with Single Sign-On
If your organization utilizes and requires Single Sign-On for account access, e.g. Okta, then username and password based auth cannot be used for your application. Instead, we recommend using the JWT auth flow which does not have this restriction.
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 |
Technical discussion
There is only one call to make in the password authorizaton flow: the call to request an access token. This call is described below.
Access token request
HTTP Headers
| Header | Value |
|---|---|
Content-type |
application/x-www-form-urlencoded |
Authorization |
Basic + base64_encoded( Client ID + ":" + Client Secret ) |
POST parameters
| Parameter | Type | Description |
|---|---|---|
grant_type |
string | Required. Must be set to password for Resource Owner Credentials flow |
access_token_ttl |
integer | Optional. Access token lifetime in seconds; the possible values are from 600 sec (10 min) to 3600 sec (1 hour). The default value is 3600 sec. If the value specified exceeds the default one, the default value is set. If the value specified is less than 600 seconds, the minimum value (600 sec) is set |
refresh_token_ttl |
integer | Optional. Refresh token lifetime in seconds. The default value depends on the client application, but as usual it equals to 7 days. If the value specified exceeds the default one, the default value is applied. |
username |
string | Phone number in E.164 format or email address linked to account or extension. Please note: You cannot use one and the same email address for authorization on different extensions (even if they are assigned to different accounts) |
extension |
string | Optional. Extension short number. If company number is specified as a username, and extension is not specified, the server will attempt to authenticate client as main company administrator |
password |
string | Required. User's password |
Sample Request
POST /restapi/oauth/token HTTP/1.1
Accept: application/json
Content-Type: application/x-www-form-urlencoded
Authorization: Basic cmVsLWFsbC1wZXJtaXNzaWXFjMmpRZmlQcnlkSUkweE92QQ==
grant_type=password&username=18559100010&extension=101&password=121212
Access token response
Response parameters
| Parameter | Type | Description |
|---|---|---|
access_token |
string | Access token to pass to subsequent API requests |
expires_in |
integer | Issued access token TTL (time to live), in seconds |
refresh_token |
string | Refresh token to get a new access token, when the issued one expires |
refresh_token_expires_in |
integer | Issued refresh token TTL (time to live), in seconds |
token_type |
string | Type of token. The only possible value supported is 'Bearer'. This value should be used when specifying access token in Authorization header of subsequent API requests |
owner_id |
string | Extension identifier |
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,
"owner_id" : "256440016"
}