Obtaining a RingCX access token with a RingCentral Login
To access RingCX APIs, you need to create a RingCX App, and then with the client credentials, request a RingCX access token. Once you have created an app, request a RingEX access token and then using a RingCX API to create a RingCX access token. Then the RingCX Access Token can be used to access RingCX APIs.
RingCX APIs for RingEX customers are rooted at: https://ringcx.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.
When you are done, you will be taken to the app's dashboard. Make note of the Client ID. You will use this credential when authenticating your application in upcoming steps. Next, make sure to have your RingCX account number ready. If you do not have an RingCX account, please reach out to our Sales team to sign up for an RingCX account.
Retrieve RingCentral access token
Now retrieve a RingCentral access token using the following instructions:
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://ringcx.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://ringcx.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 the RingEX authentication flow.
$ curl -XPOST https://ringcx.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://ringcx.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 = "ringcx.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://ringcx.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://ringcx.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://ringcx.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://ringcx.ringcentral.com/voice/api/v1/admin/accounts
Authorization: Bearer <rcRingCXAccessToken>
Here is an example cURL command:
curl -X GET https://ringcx.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://ringcx.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
}