Service Account

This section will introce: what is a service account, and how to manage and use the platform as well as agent services via a service account.

What is Service Account?

The Service Account is a virtual account used to invoke the platform's APIs for building conversational capabilities. Once the service account is authenticated, developers can use the Open Platform capabilities without relying on web-based applications.

What is Open Platform?

The Open Platform provide all APIs for developers to communicate with the agent through HTTP requests.

You can directly call those APIs to:

• Integrate with IM system to get response from the agent.
• Configure the data of the agent.
• Get analysis data of the agent's sessions.
• Get partial NLU results.

Create and use a service account

To ensure the security of the API, the following parameters need to be appended to the Request Headers object each time the API is needed: Account ID and secret for authentication.

Create a service account

1. On the Service Account page, click the "+CREATE" button to create a new service account and get the Account ID and Secret.

   

2. If you need to change your account secret, click the "Reset Secret" in the line you want to reset.

   

Call APIs in open platform

The open platform provides various APIs, you can use them by sending an HTTP/HTTPS request to the platform server address, with the appropriate request parameters added to the request, processing results will be returned after the call.

When requesting open platform APIs, you need to use HTTP/HTTPS protocol, JSON data format and UTF-8 encoding.

If using POST requests, you need to set Content-Type : application/json in HTTP Headers.

Basic Structure of an API is:

https://{Endpoint}/{version}/{type}/{action}

- Endpoint: the server addresss where you deploy the server.
- version: version of the API, check in the API doc.
- type: type of the API, check in the API doc.
- action: actions you want to perform, such as "user-attribute/create" is the action you want to create a user attribute.

For more details, see APIs Doc.

Authentication by service account

To ensure the security, you need to authenticate the usage of APIs through the service account.

The steps are as follows:

1. Get the account ID and Secret：

   

2. The request is authenticated using the four Api-Auth-xxx key-value pairs contained in the HTTP Request Headers, and each call to the API requires the following check parameters to be appended to the Request Headers object:

Parameters	Description
Api-Auth-pubkey	Account ID
Api-Auth-nonce	A random number generated by the caller. There is no limit to the number of bits, and the random number cannot be repeated in each request within one minute.
Api-Auth-sign	Generated by "Secret" and random number "Api-Auth-nonce". See demo.
Api-Auth-timestamp	The second-level timestamp when the server generates the random number.

curl sample command：

curl -X POST https://{Endpoint}/chatbot/v1alpha1/agents/{agentId}/channels/{channelId}/users/mutate \
-H 'Api-Auth-pubkey: {{pubkey-value}}' \
-H 'Api-Auth-nonce: {{nonce-value}}' \
-H 'Api-Auth-sign: {{sign-value}}' \
-H 'Api-Auth-timestamp: {{timestamp-value}}' \
-H 'Content-Type:application/json'
-d '{ \
   "operations": [
      {
         "create": {
         "username": "curl_username",
         "nickename": "curl_nickname",
         "avatarUrl": ""
         },
      }
   ]    
}'

caution

{agentId}, {channelId} and four Api-Auth-xxx values need to be placed by real data.