Using access tokens
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:
Basic + base64_encoded( Client ID + ":" Client Secret )
|Required. The token to revoke.
POST /restapi/oauth/revoke HTTP/1.1
Authorization: Basic cmVsLWFsbC1wZXJtaXNzaWXFjMmpRZmlQcnlkSUkweE92QQ==
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 by way of the HTTP Bearer authentication scheme. For example:
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA
Option 2. Access token query parameter
Transmit the access token as a query parameter specified as a value. For example: