Authorization Code Flow

The "Authorization Code Flow," also referred to as a "3-legged authorization flow" or simply "OAuth" is the most common and recommended form of authenticating RingCentral users within the context of an application. This process conforms to the OAuth 2.0 standard and works to:

• Keep a user's auth credentials secure, and out of the hands of a third-party.
• Disclose what permissions an app requires.
• Prompt the user to explicitly authorize an app to access their data.
• Provide the developer with a token that can used to by their application to act on a user's behalf.

The general flow looks like this:

The step-by-step details of this flow are explained below.

Step 1. Request authorization code

When your application needs to access a user's data, redirect the user to the RingCentral API server. Generate a URL to request access from endpoint /restapi/oauth/authorize. This request must be in the application/x-www-form-urlencoded format and must contain the following parameters in the HTTP request body:

Example Login URL

Below is an example login URL to initiate the authorization flow. We recommend developers use an SDK to generate this URL in a more automated fashion.

https://platform.ringcentral.com/restapi/oauth/authorize?response_type=code&redirect_uri=<my_uri>&client_id=<client_id>&brand_id=7710&display=&prompt=

Step 2. User login and consent

On this step your app’s user is redirected by the browser to a RingCentral authorization page, where user can view the list of permissions your app is asking for.

After confirming the permissions, the user enters their RingCentral credentials, and the browser is then redirected to the "Redirect URI" you’ve provided in the request.

Step 3. Handling authorization code server response

The authorization server responds to your application's access request by using the URL specified in the request.

• If the user approves the access request, then the response contains an authorization code.
• If the user does not approve the request, the response contains an error message.

An authorization code response contains:

If authentication has been passed successfully, your application will get a response similar to the following:

HTTP/1.1 302 Found
Location: https://myapp.example.com/oauth2Callback?code=SplxlOBeZQQYbYS6WxSbIA&state=xyz&expires_in=60

Step 4. Exchange code for token

After the web server receives the authorization code, it can exchange the authorization code for an access token using token endpoint /restapi/oauth/token (API group is Auth).

Token requests must include client authentication credentials (see Client Authentication section).

Request Body

Content Type: application/x-www-form-urlencoded

Step 5. Handling token server response

The server responds with an access token which can presented in subsequent requests in the HTTP Authorization header to authenticate API Calls. The response will contain the following parameters:

Example

POST /restapi/oauth/token HTTP/1.1 
Accept: application/json 
Content-Type: application/x-www-form-urlencoded 
Authorization: Basic cmVsLWFsbC1wZXJtaXNzaWXFjMmpRZmlQcnlkSUkweE92QQ==code=U0pDMTFQMDFQQVMwM
  XxBQUJfTVpHWk5lM29zNVFmWnNHQ01MSmJuMHJmNGlRcnRaeEptTWlPS0MzUTdYRDdSTURiaHBuWHZINGM2WTdqaWlBOE
  VhRHNxRWdJVUNYQjd4dmJsWHJoVVlWQVN2SFo2YWJPanJsRkFWZk9SMm5lek0tWnF5d3h8C3AnYOPxO0flEwO6Ffoq9Tl
  qs1s&grant_type=authorization_code&redirect_uri=https%3A%2F%2Fmyapp.acme.com%2Foauth2redirect              

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"
}