OAuth 2.0
Authorization
Authorization Code Flow
Returns link to a login page location.
Usage Plan Group
Auth
GET /restapi/oauth/authorize
Request Headers
Client app may pass localization language code value in Accept-Language header. But if any of these parameters localeId or ui_locales is specified, the header value is overwritten.
Query Parameters
| Parameter | Description | ||
|---|---|---|---|
| response_type | string | Must be set to code | |
| redirect_uri | string | This is a callback URI which determines where the response is sent. The value of this parameter must exactly match one of the URIs you have provided for your app upon registration | |
| client_id | string | Identifier (key) of a client application | |
| state | string | Client state. Returned back to the client at the end of the flow | |
| brand_id | string | Brand identifier. If it is not provided in request, server will try to determine brand from client app profile. The default value is 1210 – RingCentral US | |
| display | string | Style of login form. The default value is page. The popup and touch values are featured for mobile applications | pagepopuptouchmobile |
| prompt | string | Specifies which login form will be displayed. Space-separated set of the following values: login – official RingCentral login form, sso – Single Sign-On login form, consent – form to show the requested scope and prompt user for consent. Either login or sso (or both) must be specified. The default value is login&sso | |
| localeId | string | Localization code of a language. Overwrites Accept-Language header value | |
| ui_locales | string | Localization code of a language. Overwrites localeId parameter value | |
| ui_options | string | User interface options data | hide_logo hide_tos hide_remember_me external_popup old_ui |
Response Body
Link to a login page location.
Example
Request
GET /restapi/oauth/authorize?client_id=A50F55593E224b381E81D6A969391D0e49E27FB9A1C3
&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Foauthredirect&response_type=code&state=ABC123&prompt=login
Response
HTTP/1.1 302 Found
Location:
https://service.ringcentral.com/mobile/loginDispatcher?session=2008293087662283621&clientId=A50F55593E224b381E81D6A969391D0e49E27FB9A1C3
&state=ABC123&brandId=1210&appUrlScheme=https%3A%2F%2Fmyapp%2Eexample%2Ecom%2Foauthredirect&localeId=en_US&display=page&prompt=login&hideNavigationBar=true
Implicit Grant Type Flow
Returns login page location. And upon successful login – access token embedded in a link redirecting to a client web application. Please note: Access token obtained via this request expires in an hour and can be refreshed by sending this request repeatedly.
Request Headers
Client app may pass localization language code value in Accept-Language header. But if any of these parameters localeId or ui_locales is specified, the header value is overwritten.
Query Parameters
| Parameter | Description | ||
|---|---|---|---|
| response_type | string | Must be set to token | |
| redirect_uri | string | This is a callback URI which determines where the response is sent. The value of this parameter must exactly match one of the URIs you have provided for your app upon registration | |
| client_id | string | Identifier (key) of a client application | |
| state | string | Client state. Returned back to the client at the end of the flow | |
| brand_id | string | Brand identifier. If it is not provided in request, server will try to determine brand from client app profile. The default value is 1210 – RingCentral US | |
| display | string | Style of login form. The default value is page. The popup and touch values are featured for mobile applications | pagepopuptouchmobile |
| prompt | string | Specifies which login form will be displayed. Space-separated set of the following values: login – official RingCentral login form, sso – Single Sign-On login form, consent – form to show the requested scope and prompt user for consent. Either login or sso (or both) must be specified. Please note: The value must be set to none for all requests except for the first one | |
| ui_locales | string | Localization code of a language. Overwrites localeId parameter value | |
| localeId | string | Localization code of a language. Overwrites Accept-Language header value | |
| ui_options | string | User interface options data | hide_logo hide_tos hide_remember_me external_popup old_ui |
Response Body
Link to a login page location.
After successful user login the browser will pass the hash fragment with access token directly to the application redirect URI.
Example
Request
GET https://api.ringcentral.com/restapi/oauth/authorize?response_type=token&client_id=9oQlL98tTQGhpdqq5KB60Q&state=xyz&prompt=login%20consent&
redirect_uri=http%3A%2F%2Fmyapp%2Eexample%2Ecom%2Foauthredirect HTTP/1.1
Response
HTTP/1.1 302 Found
Location:
https://service.ringcentral.com/mobile/loginDispatcher?session=2008293087662283621&clientId=9oQlL98tTQGhpdqq5KB60Q&state=xyz
&brandId=1210&appUrlScheme=http%3A%2F%2Fmyapp%2Eexample%2Ecom%2Foauthredirect&localeId=en_US&display=page&prompt=login%20consent&hideNavigationBar=true
Callback Request
http://myapp.example.com/oauthredirect#access_token=tuyt43gjhg6u54uiy6iuyhh3k45jh34k5hO6884534jk5h
OAuth 2.0
Get Token
This endpoint enables client applications to get access tokens for making API requests. Requests to this endpoint must be authenticated with HTTP Basic scheme using the client ID and client secret as login and password, correspondingly.
Authorization Code Flow
Each time you call token endpoint using this flow a new client session starts. It is associated with the issued token pair: access token and refresh token, returned in response to this request. To continue the session you can refresh the obtained access token and refresh token as many times as you need, using Refresh Token flow or the same flow.
To start another client session you should call token endpoint using this flow again. Please consider that only 5 simultaneously active sessions per extension per application are supported. Thus if you exceed the number of sessions started per extension per application, the oldest one is ended.
Usage Plan Group
Auth
POST /restapi/oauth/token
Form Data Parameters
| Parameter | Description | ||
|---|---|---|---|
| grant_type | string | Must be set to authorization_code for authorization code flow | |
| code | string | Authorization code | |
| redirect_uri | string | This is a callback URI which determines where the response is sent. The value of this parameter must exactly match one of the URIs you have provided for your app upon registration | URI |
| access_token_ttl | integer | 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 | Refresh token lifetime in seconds. The maximum allowed value is 7 days. If the value is not specified or exceeds the maximum value, then by default the maximum value is applied |
Response Body
| Parameter | 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 | |
| scope | string | List of permissions allowed with this access token, white-space separated | |
| 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 | |
| endpoint_id | string | Unique identifier of a client application. You can pass it in request according to pattern [a-zA-Z0-9_\-]{1,64}. Otherwise it is auto-generated by server. The value will be returned in response in both cases |
Example
Request
POST /restapi/oauth/token
code=U0pDMDFQMDRQQVMwMnxBQUFGTVUyYURGYi0wUEhEZ2VLeGFiamFvZlNMQlZ5TExBUHBlZVpTSVlhWk
xYajg5aDA3UVJmZ3VHdTNOTk05YkR0MEw0RkhnMlRPdTZuMTJSdEYwUkZyZHBSNWtLUzlzc1V8eW1OWVhRf
FdnUW5QcExvYVhrN3lqY3p5NEJwWHc&grant_type=authorization_code&redirect_uri=https://www.example.com/myapp
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"
}
Password Flow
Each time you call token endpoint using this flow a new client session starts. It is associated with the issued token pair: access token and refresh token, returned in response to this request. To continue the session you can refresh the obtained access token and refresh token as many times as you need, using Refresh Token flow or the same flow.
To start another client session you should call token endpoint using this flow again. Please consider that only 5 simultaneously active sessions per extension per application are supported. Thus if you exceed the number of sessions started per extension per application, the oldest one is ended.
Usage Plan Group
Auth
POST /restapi/oauth/token
Request Headers
The Content-Type header should be specified as application/x-www-form-urlencoded. Please note: Request body should be encoded appropriately. For example email john+doe@example.com as username parameter should be specified so – john%2Bdoe%40example.com.
Form Data Parameters
| Parameter | Description | ||
|---|---|---|---|
| grant_type | string | Must hold password value for Resource Owner Credentials flow. If client application is not authorized by the specified grant_type, response does not contain refresh_token and refresh_token_ttl attributes | |
| access_token_ttl | integer | 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 | 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. If client specifies refresh_token_ttl<=0, refresh token is not returned even if the corresponding grant type is supported | |
| username | string | Phone number in E.164 format (including the following format <phone number>*<ext. number>) or an 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 | Extension short number. Please note: If company number is specified as username, and extension number is not provided neither in username nor in extension attributes, then the server attempts to authenticate the client as a main company administrator. If a username is provided in a new format – with extension specified via asterisk (for example 18001234567*123) then extension attribute is ignored | |
| password | string | User password | |
| endpoint_id | string | Unique identifier of a client application. You can pass it in request according to pattern [a-zA-Z0-9_\-]{1,64}. Otherwise it is auto-generated by server. The value will be returned in response in both cases |
Response Body
| Parameter | 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 | |
| scope | string | List of permissions allowed with this access token, white-space separated | |
| 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 |
Example 1: Phone number as a username
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*123&password=121212
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"
}
Example 2: Email address as a username
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=john%2Bdoe%40example.com&password=121212
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"
}
Refresh Token Flow
Each time you call token endpoint using this flow, you continue current client session, and receive a new token pair: access token and refresh token in response to this request. The old token pair immediately becomes inactive.
Usage Plan Group
Auth
POST /restapi/oauth/token
Form Data Parameters
| Parameter | Description | ||
|---|---|---|---|
| refresh_token | string | Previously issued refresh token | |
| grant_type | string | Must hold refresh_token value | |
| endpoint_id | string | Unique identifier of a client application. If not specified, the previously specified or auto-generated value is used by default |
Response Body
| Parameter | 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 | |
| scope | string | List of permissions allowed with this access token, white-space separated | |
| 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 |
Example
Request
POST /restapi/oauth/token HTTP/1.1
Accept: application/json
Content-Type: application/x-www-form-urlencoded
Authorization: Basic cmVsLWFsbC1wZXJtaXNzaWXFjMmpRZmlQcnlkSUkweE92QQ==
refresh_token=BCMDFUMDRKV1MwMXx5d5dwzLFL4ec6U1A0XMsUv935527jghj48&grant_type=refresh_token
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" : 6048799,
"scope" : "AccountInfo CallLog ExtensionInfo Messages SMS"
}
OAuth 2.0
Revoke Token
Revokes access/refresh token. Requests to this endpoint must be authenticated with HTTP Basic scheme using client ID and client secret as login and password, correspondingly.
Usage Plan Group
Auth
/restapi/oauth/revoke
Form Data Parameters
| Parameter | Description | ||
|---|---|---|---|
| token | string | Active access or refresh token to be revoked |
Response Body
None
Example
Request
POST /restapi/oauth/revoke HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Authorization: Basic M2ZmYjNlMThkZDU4ZDE1YTk2NTIwYmFmNzUzZjBiNzk6MzI5OWQ0NTg5NGU1Njg5ODllOTY1ZTFiMTk5MGU2OTI
token=U0pDMDFQMDFKV1MwMXwJ_W7L1fG4eGXBW9Pp-otywzriCw
Response
HTTP/1.1 200 OK
Site Title 