Authentication

Owned by SUPPORT
Last updated: Sept 03, 2024
7 min read

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 ID of Authentication, follow these steps:

  1. Log in to your CX Control Panel.

  2. From the left navigation menu, go to Security -> Authentication -> OAuth Client.

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

图片-20240829-131221.png

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

  2. Application Name: The name displayed to users when asked to grant access to your application or when viewing all apps that have been granted access.

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

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

Step 2: Get the OAuth access token

To get the OAuth Access Token, 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.example.net/openapi/admin/v1.0/tenant/page?pageIndex=1&pageSize=2&title=si' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer {access_token}'

Response example:

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 Security -> Authentication -> API Key.

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

  1. 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 API KEY, the following will use cURL as an example:

cURL Request Example:

Response example:

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.

Never give your API KEY to a third-party platform

Your API KEY can give access to your private CX data and should be treated like a password.