Using access tokens

OAuth tokens are used to provide an authorization context in each request. It is important to understand the distinctions between token types:

• An access token is a token issued by the authorization server and used by the application to make requests to all endpoints that require authentication.

• A refresh token can be provided alongside the access token after successful authorization. It is a single-use token used to fetch a new access token when it is expired or close to expiration. The refresh token itself cannot be used to access protected resources.

Access token expiration and invalidation

Tokens may be invalidated for any of the following reasons:

• Access and/or refresh tokens expiration.
• The app's authorization session is terminated by the end-user (that causes all active access and refresh tokens to get invalidated).
• The user's password was changed, which caused invalidating all sessions established with this credential and corresponding tokens.
• The company administrator enforces an "Absolute Session Timeout" setting that prohibits any session from exceeding the defined time-to-live interval.
• The application reached the limit (usually five) of parallel active sessions for the same user.

If an expired or invalidated token is used, RingCentral rejects the request with an "HTTP 401 Unauthorized" error.

When tokens expire or are invalidated, applications must obtain a new access token.

Access token revocation

There are some situations when the user may want to revoke the already granted access in order to stop application activity. To revoke access/refresh tokens the following request is used:

HTTP Headers

POST Parameters

Sample Request

POST /restapi/oauth/revoke HTTP/1.1 
Accept: application/json 
Content-Type: application/x-www-form-urlencoded 
Authorization: Basic cmVsLWFsbC1wZXJtaXNzaWXFjMmpRZmlQcnlkSUkweE92QQ==

token=U0pDMTFQMDFQQVMwMXxBQUJfTVpHWk5lM29zNVFmWnNHQ01MSmJuMHJmNGlRcnRaeEptTWlPS0MzUTdYRDdSTURiaH
  BuWHZINGM2WTdqaWlBOEVhRHNxRWdJVUNYQjd4dmJsWHJoVVlWQVN2SFo2YWJPanJsRkFWZk9SMm5lek0tWnF5d3h8C3A
  nYOPxO0flEwO6Ffoq9Tlqs1s

Please note that while the revocation request accepts just one token, it actually terminates the entire authorization session associated with this token, i.e., invalidates ALL active access and refresh tokens for this session.

Using access tokens to call RingCentral APIs

Once an access token is obtained, it should be transmitted with each call to the RingCentral API using one of the following methods:

Option 1: Bearer (recommended)

Transmit the access token through the Authorization header with the HTTP Bearer authentication scheme (recommended). For example:

GET /restapi/v1.0/account/1110475004/extension/1110475004/address-book/contact/29874662828
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA 
Host: platform.ringcentral.com
Accept: application/json
Connection: keep-alive

Option 2. Access token query parameter

Transmit the access token as a query parameter specified as a value. For example:

GET /restapi/v1.0/account/1110475004/extension/1110475004/address-book/contact/29874662828
   ?access_token=2YotnFZFEjr1zCsicMWpAA
Host: platform.ringcentral.com
Accept: application/json
Connection: keep-alive