Using access tokens

Last updated: 2022-01-13 Contributors Byrne Reese
Edit this page

Need help authenticating your application?

This guide is intended to assist developers in using access tokens once they have been acquired by going through one of authorization flows:

Tokens are used to provide a context in each request for authorization or authentication. It is important to understand distinctions between token types:

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

  • A refresh token can be provided alongside the access token during authorization. It is a single-use token used to fetch a new access token before it expires. 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 refresh tokens can expire.
  • Access and refresh tokens may be revoked by the end-user at any time.
  • If a user's credentials are changed (via RingCentral's Service Web, Mobile Web or Admin Interface sites) all issued tokens are invalidated immediately, and all established sessions are terminated.

In an expired or invalidated token is used, RingCentral will respond with an HTTP error of "401 Unauthorized."

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 token the following request is used:

HTTP Headers

Header Value
Content-type application/x-www-form-urlencoded
Authorization Basic + base64_encoded( Client ID + ":" Client Secret )

POST Parameters

Parameter Type Description
token string Required. The token to revoke.

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

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:

Transmit the access token by way of the HTTP Bearer authentication scheme. 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