Obtaining an RingCX Access Token with a RingCentral Login

Last updated: 2023-12-09Contributors
Edit this page

To access RingCX APIs, you need to create an RingCX App, and then with the client credentials, request an RingCX Access Token. Once you have created an App, request a RingCentral Access Token and then using an RingCX API to create an RingCX Access Token. Then the RingCX Access Token can be used to access RingCX APIs.

Note: RingCX APIs for MVP customers are rooted at:

https://engage.ringcentral.com/voice/api/

Create an App

The first thing we need to do is create an app in the RingCentral Developer Portal. This can be done quickly by clicking the "Create RingCX App" button below. Just click the button, enter a name and description if you choose, and click the "Create" button. If you do not yet have a RingCentral account, you will be prompted to create one.

Important

While you can create a RingCentral account through the Developer Portal, you will need a production account to use RingCX APIs at this time. Make sure to login to your developer account using the same credentials as your production RingCentral account. The RingCentral account created via the Developer Portal will not work.

Create RingCX App

  1. Login or create an account if you have not done so already.
  2. Go to Console/Apps and click 'Create App' button.
  3. Select the App Type, "REST API App (most common)," then click Next.
  4. Give your app a name and description, then scroll to the "Auth" section.
  5. In the "Auth" section:
    • Select 'JWT auth flow' for the authentication method.
    • Under "Issue refresh tokens?" make sure the box for 'Yes' is highlighted.
  6. In the "Security" section, specify only the following "Application Scopes":
    • Read Accounts
  7. In the same "Security" section, make sure to select:
    • This app is private and will only be callable using credentials from the same RingCentral account.

When you are done, you will be taken to the app's dashboard. Make note of the Client ID. This is your Client ID for the App in the Sandbox. To start using RingCX APIs, you need to graduate your app to Production and use the Production Client ID and Client Secret in upcoming steps. Make sure to have your RingCX account number ready for the next step. If you do not have an RingCX account, please reach out to our Sales team to sign up for an RingCX account.

Request Graduation of RingCX App

Retrieve RingCentral Access Token

Now retrieve a RingCentral access token using the following instructions:

RingCentral Authentication

Retrieve RingCentral RingCX Access Token

Once you have a RingCentral Access Token, call the following RingCX API to receive an RingCX Bearer access token.

Request

POST https://engage.ringcentral.com/api/auth/login/rc/accesstoken
Content-Type: application/x-www-form-urlencoded

rcAccessToken=<rcAccessToken>&rcTokenType=Bearer

It's also a good idea to use a refresh token as the access token expires in 5 minutes.

POST https://engage.ringcentral.com/api/auth/login/rc/accesstoken?includeRefresh=true
Content-Type: application/x-www-form-urlencoded

rcAccessToken=<rcAccessToken>&rcTokenType=Bearer

Where:

  • <rcAccessToken> is the RingCentral Access Token you received from RingCentral MVP authentication flow.
$ curl -XPOST https://engage.ringcentral.com/api/auth/login/rc/accesstoken \
      -d 'rcAccessToken=<rcAccessToken>' \
      -d 'rcTokenType=Bearer'
package main

import(
      "fmt"
      "encoding/json"
      "io/ioutil"
      "net/url"
    )

// RingCXToken is an example and does not cover all the
// properties in the API response.
type RingCXToken struct {
        AccessToken string `json:"accessToken"`
        TokenType   string `json:"tokenType"`
}

func RcToEvToken(rctoken string) (string, error) {
    res, err := http.PostForm(
            "https://engage.ringcentral.com/api/auth/login/rc/accesstoken",
            url.Values{"rcAccessToken": {rctoken}, "rcTokenType": {"Bearer"}})
    if err != nil {
            return "", err
    }
    if res.StatusCode >= 300 {
            return "", fmt.Errorf("Invalid Token Response [%v]", res.StatusCode)
    }
    ringCXToken := RingCXToken{}
    bytes, err := ioutil.ReadAll(res.Body)
    if err != nil {
            return "", err
    }
    err = json.Unmarshal(bytes, &ringCXToken)
    return ringCXToken.AccessToken, err
}

func main() {
    rctoken := "myRcToken"

    evtoken, err := RcToEvToken(rctoken)
    if err != nil {
            log.Fatal(err)
    }
    fmt.Println(evtoken)
}
var https = require('https')

var RC_ACCESS_TOKEN = "VALID-RINGCENTRAL-ACCESS-TOKEN"

var url = "engage.ringcentral.com"
var path = '/api/auth/login/rc/accesstoken'
var body = 'rcAccessToken=' + RC_ACCESS_TOKEN + "&rcTokenType=Bearer"
var headers = { 'Content-Type': 'application/x-www-form-urlencoded' }

var options = {host: url, path: path, method: 'POST', headers: headers};
var post_req = https.request(options, function(res) {
      var response = ""
      res.on('data', function (chunk) {
          response += chunk
      }).on("end", function(){
          if (res.statusCode == 200){
              var tokensObj = JSON.parse(response)
              console.log(tokensObj.accessToken)
          }else{
              console.log(response)
          }
      });
    }).on('error', function (e) {
        console.log(e)
    })
post_req.write(body);
post_req.end();
import requests

RC_ACCESS_TOKEN = "VALID-RINGCENTRAL-ACCESS-TOKEN"
url = "https://engage.ringcentral.com/api/auth/login/rc/accesstoken"
body = "rcAccessToken=%s&rcTokenType=Bearer" % (RC_ACCESS_TOKEN)
headers = {
              'Content-Type': 'application/x-www-form-urlencoded'
          }
try:
    res = requests.post(url, headers=headers, data=body)
    if res.status_code == 200:
        jsonObj = json.loads(res._content)
        print (jsonObj['accessToken'])
    else:
        print (res._content)
except Exception as e:
    raise ValueError(e)
<?php
$RC_ACCESS_TOKEN = "VALID-RINGCENTRAL-ACCESS-TOKEN";

$url = "https://engage.ringcentral.com/api/auth/login/rc/accesstoken";
$body = 'rcAccessToken=' . $RC_ACCESS_TOKEN . "&rcTokenType=Bearer";
$headers = array ('Content-Type: application/x-www-form-urlencoded');

try{
    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
    curl_setopt($ch, CURLOPT_POST, TRUE);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
    curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 0);
    curl_setopt($ch, CURLOPT_TIMEOUT, 600);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
    $strResponse = curl_exec($ch);
    $curlErrno = curl_errno($ch);
    if ($curlErrno) {
        throw new Exception($curlErrno);
    } else {
        $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        curl_close($ch);
        if ($httpCode == 200) {
            $tokensObj = json_decode($strResponse);
            print ($tokensObj->accessToken);
        }else{
            print ($strResponse);
        }
    }
}catch (Exception $e) {
    throw $e;
}

Response

The response will contain the accessToken property that can be used in an API call, as well as the refreshToken property that can be used to refresh the access token when the access token expires. Make sure to save both the accessToken and refreshToken for future API calls. Take note of the accountId property as that will be used to make future API calls.

The following is an abbreviated response.

{
  "refreshToken":"<rcRingCXRefreshToken>",
  "accessToken":"<rcRingCXAccessToken>",
  "tokenType":"Bearer",
  "agentDetails":[
    {
      "agentId":111111,
      "firstName":"John",
      "lastName":"Wang",
      "email":"[email protected]",
      "username":"[email protected]",
      "agentType":"AGENT",
      "rcUserId":222222,
      "accountId":"333333",
      "accountName":"RingForce",
      "agentGroupId":null,
      "allowLoginControl":true,
      "allowLoginUpdates":true
    }
  ],
  "adminId":1111,
  "adminUrl":"/voice/admin/",
  "agentUrl":"/voice/agent/",
  "ssoLogin":true
}

Example RingCX API Call

The following is an example RingCX API Call using a RingCentral RingCX Access Token.

GET https://engage.ringcentral.com/voice/api/v1/admin/users
Authorization: Bearer <rcRingCXAccessToken>

Get Accounts

Another method to try is to retrieve the accounts this user has access to. The main account is the top level account and is consider a container for the sub-accounts that most operations are performed on.

GET https://engage.ringcentral.com/voice/api/v1/admin/accounts
Authorization: Bearer <rcRingCXAccessToken>

Here is an example cURL command:

curl -X GET https://engage.ringcentral.com/voice/api/v1/admin/accounts -H "Authorization: Bearer {rcRingCXAccessToken}"

Refresh RingCentral RingCX Access Token

The RingCentral RingCX Access Token will only live for a few minutes (currently 5 minutes) before needing to be refreshed. If the access token is expired, the API request will respond with:

401 Unauthorized

Jwt is expired

Use the refreshToken to refresh the RingCentral RingCX access token, by calling the following RingCX API.

Request

POST https://engage.ringcentral.com/api/auth/token/refresh
Content-Type: application/x-www-form-urlencoded

refresh_token=<rcRingCXRefreshToken>&rcTokenType=Bearer

Where:

  • <rcRingCXRefreshToken> is the RingCentral Refresh Token you received from RingCentral RingCX authentication flow.

Response

The response will contain the same accessToken property that can be used in an API call, but the refreshToken property will be a new refresh token that can be used to refresh the access token when the access token expires. Make sure to save the new refreshToken for future refresh token API calls.

The following is an abbreviated response.

{
  "refreshToken":"<rcRingCXRefreshToken>", //Save this as it will be new.
  "accessToken":"<rcRingCXAccessToken>",
  "tokenType":"Bearer",
  "agentDetails":[
    {
      "agentId":111111,
      "firstName":"John",
      "lastName":"Wang",
      "email":"[email protected]",
      "username":"[email protected]",
      "agentType":"AGENT",
      "rcUserId":222222,
      "accountId":"333333",
      "accountName":"RingForce",
      "agentGroupId":null,
      "allowLoginControl":true,
      "allowLoginUpdates":true
    }
  ],
  "adminId":1111,
  "adminUrl":"/voice/admin/",
  "agentUrl":"/voice/agent/",
  "ssoLogin":true
}