Page Comparison

...

To access the CloudCX REST API, you have two authentication options: One for OAuth2 and another for API KEY(access token).

...

OAuth Authentication

OAuth2 is a secure and widely accepted protocol for authorization. It allows the work order system to access resources from the service provider on behalf of the user, without sharing their credentials. The process involves several steps:

Step 1: Get the Client ID of OAuth

To get the Client

...

（1）Log ID of Authentication, follow these steps:

1. Log in to your

...

1. CX Control Panel.

...

1. From the left navigation menu, go

...

1. to Global Settings > Security > OAuth Client.

...

1. If OAuth Client has been created already, just click

...

1. Operation->Edit, then get the Client ID. Otherwise

...

1. . Click New OAuth Client.

...

（4）Enter

1. Enter the following OAuth Client details, and click Save:

...

1. Application Name: The

...

1. name

...

1. displayed to users when asked to grant access to your application or when viewing all apps that have been granted access.

2. Description: A short description of your

...

1. client for users to consider access to your application.

...

Your OAuth Client is successfully created and listed on the OAuth Client page, and get gets the Client ID from the OAuth Client.

Step 2: Get the OAuth

...

access token

To get the OAuth Access Token, follow these steps(Postman or CURL):

Postman

（1）Log in to Postman.

（2）Go to Home > Create New > HTTP Request.(Menu might be differect on different Postman version)

（3）Select the POST method and provide the URL. While generating an access token, the API request should start with your platform domain followed by the curl command, which is different from other API requests. For example, if your Control Panel domain is cx.cloudcx.net, the API request should be https://cx.cloudcx.net/oauth/token.

...

（4）Go to Body > x-www-form-urlencoded tab.

（5）Input the following Keys and their Values.

...

For example:

• email: XXXXXXXX

• password: XXXXX

• grant_type: password

• client_id: XXXXXX

（6）Click Send. You get the OAuth Access Token to call APIs.

（7）Copy the OAuth Access Token to your clipboard.

...

...

the following will use cURL as an example:

cURL Request example:

curl --location 'https://cloudcx.example.com/oauth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=2603****************814845' \
--data-urlencode 'client_secret=6d624c35-978b-*********-59d727f2ea19' \
--data-urlencode 'grant_type=password' \
--data-urlencode 'username=si*****' \
--data-urlencode 'password=A******'

Response example:

{
    "access_token":"eyJraWQiOiJiM2Y1OWZ*************************************iOiJSUzI1NiJ9.eyJzdWIiOiIyNjAzOTA2MzQ0OTE3OTI4MzE4MTQ4NDUiLCJhdWQiOiIyNjAzOTA2MzQ0OTE3OTI4MzE4MTQ4NDUiLCJuYmYiOjE3MjM1MTU4NDUsInVzZXItaWQiOiJiMjQyM2Y0YS1lYTgxLTQ4OGYtOTcwYy0xNmQ0YTI3NWZiNTIiLCJpc3MiOiJodHRwOi8vY2xvdWRjeC5jbG91ZGZvbi5uZXQiLCJleHAiOjE3MjM1MTk0NDUsImlhdCI6MTcyMzUxNTg0NX0.nWRKxWBNWMbI8v_EqcJsUNLrNqQszH-E5r0vX16QojezcPu3Dbx6Mg1ukZE5JRVbZlDCfqnwHA-dyW80dm71iyKtlJZn0XMFrjJlsVtXHKIlX5HucJrN6RTN1RxLHpDxRpcbWHZWQBB_MZCKyUKP-X2-I3vFZr2wIutaemmBg2UAtHjNsqqrDZEmimfy-PDSCMl6VphcMhtWXtYKdFMiaJgrxoQE-hVNjSaQZuUs6XHN_JK_RsDti8-MDpLYD7FsAD_8lk0h1gX3poWyy7mfhLFDxbqgmHeusV4HMSE0NU-Jz9UB503UTRRmAQyoachmO5De1Q4Ct-rbFO0EU39jFw",
    "token_type":"Bearer",
    "expires_in":3599
}

Step 3: Use the OAuth access token to call an API

To call an API using the OAuth Access Token, the following will use cURL as an example:

cURL Request Example:

curl --location 'https://cloudcx.cloudfon.net/openapi/v2/user/page?pageIndex=1&pageSize=25&keywords=si' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {access_token}'

Response example:

{
  "code": "0000",
  "message": null,
  "data": {
    "totalPages": 1,
    "totalElements": 1,
    "size": 25,
    "number": 0,
    "numberOfElements": 1,
    "content": [
      {
        "id": "75d86d40-f7d9-4025-8a1c-8a868f918289",
        "loginCode": "freesiaTest",
        "roles": [
          "Admin",
          "Agents"
        ],
        "firstName": "freesia",
        "lastName": "Test",
        "email": "frees1aa@gmail.com",
        "phoneNumber": null,
        "uniqueCode": null
      }
    ]
  }
}

Access tokens have a limited lifetime and can be renewed using the refresh token, ensuring continued access without requiring the user to log in again.

API KEY Authentication

API Key authentication is a simpler form of access control, often used for interacting with APIs. It involves sending a secret key provided by the service provider with each request to authenticate the user or the client application. Here’s how it works:

Step 1: Create and get the API Key

To get the API Key of Authentication, follow these steps:

1. Log in to your CX Control Panel.

2. From the left navigation menu, go to Global Settings > Security > API Key.

3. If OAuth Client has been created already, just click Operation->Edit, then get the Client D. Otherwise. Click New API Key.

...

4. Enter the following API Key details, and click Save:

Application Name: the name of the API Key.

Description: A short description of your Client for users to consider access to your application.

...

Your API Key is successfully created and listed on the Authentication page, and get the API Key from the Authentication.

Step 2: Use the API Key of Authentication to call an API

To call an API using the OAuth Access Token, follow these steps(Postman or CURL):

Postman

（1）Select the GET method and provide the API request URL.

（2）Go to the Authorization tab and choose the authentication type as OAuth 2.0.

（3）Paste the OAuth Access Token in the Access Token field.

（4）Ensure that the Header Prefix field is Bearer.

（5）Click Send.

...

API KEY, the following will use cURL as an example:

cURL Request Example:

curl --location 'https://cloudcx.cloudfon.net/openapi/v2/user/page?pageIndex=1&pageSize=25&keywords=si' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {API KEY}'

Response example:

{
  "code": "0000",
  "message": null,
  "data": {
    "totalPages": 1,
    "totalElements": 1,
    "size": 25,
    "number": 0,
    "numberOfElements": 1,
    "content": [
      {
        "id": "75d86d40-f7d9-4025-8a1c-8a868f918289",
        "loginCode": "freesiaTest",
        "roles": [
          "Admin",
          "Agents"
        ],
        "firstName": "freesia",
        "lastName": "Test",
        "email": "frees1aa@gmail.com",
        "phoneNumber": null,
        "uniqueCode": null
      }
    ]
  }
}

API keys are simply long, unique strings that are generated for each user or client application. They are easy to implement but are less secure than OAuth2, as they do not involve dynamic tokens or user consent flows.