Obtaining an Engage Access Token with a RingCentral Login

Last updated: 2023-05-01Contributors
Edit this page

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

Note: Engage Voice APIs for Office 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 Engage Voice 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 Engage Voice 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 Engage Voice 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 Engage 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 Engage Voice account number ready for the next step. If you do not have an Engage Voice account, please reach out to our Sales team to sign up for an Engage Voice account.

Request Graduation of Engage Voice App

Retrieve RingCentral Access Token

Now retrieve a RingCentral access token using the following instructions:

RingCentral Authentication

Retrieve RingCentral Engage Access Token

Once you have a RingCentral Access Token, call the following Engage API to receive an Engage 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 Office 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"
    )

// EngageToken is an example and does not cover all the
// properties in the API response.
type EngageToken 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)
    }
    engageToken := EngageToken{}
    bytes, err := ioutil.ReadAll(res.Body)
    if err != nil {
            return "", err
    }
    err = json.Unmarshal(bytes, &engageToken)
    return engageToken.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":"<rcEngageRefreshToken>",
  "accessToken":"<rcEngageAccessToken>",
  "tokenType":"Bearer",
  "agentDetails":[
    {
      "agentId":111111,
      "firstName":"John",
      "lastName":"Wang",
      "email":"john.wang@example.com",
      "username":"john.wang@example.com",
      "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 Engage Voice API Call

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

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

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 <rcEngageAccessToken>

Here is an example cURL command:

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

Refresh RingCentral Engage Access Token

The RingCentral Engage 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 Engage access token, by calling the following Engage API.

Request

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

refresh_token=<rcEngageRefreshToken>&rcTokenType=Bearer

Where:

  • <rcEngageRefreshToken> is the RingCentral Refresh Token you received from RingCentral Engage 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":"<rcEngageRefreshToken>", //Save this as it will be new.
  "accessToken":"<rcEngageAccessToken>",
  "tokenType":"Bearer",
  "agentDetails":[
    {
      "agentId":111111,
      "firstName":"John",
      "lastName":"Wang",
      "email":"john.wang@example.com",
      "username":"john.wang@example.com",
      "agentType":"AGENT",
      "rcUserId":222222,
      "accountId":"333333",
      "accountName":"RingForce",
      "agentGroupId":null,
      "allowLoginControl":true,
      "allowLoginUpdates":true
    }
  ],
  "adminId":1111,
  "adminUrl":"/voice/admin/",
  "agentUrl":"/voice/agent/",
  "ssoLogin":true
}