API Function Specification

Current version: V6.2

Unified Authentication

Sobot open API implements a standard mechanism of using API for authorized access based on Json Web Token (JWT) to meet the needs of users' security settings.

Basic Workflow and Usage Instructions

The workflow is as follows:

1. The client uses appId and app_secret to request the server
2. The server verifies the authenticated information
3. The server sends access_token to the user via verification
4. The client stores the access_token;
5. and sends the access_token value each time a request is made (param Authorization stored in head)
6. The server verifies the access_token value and returns the data
7. The access_token carries a timeout time after it is requested, and the client should obtain the token again when the access_token timeout time is halfway over.
8. If the server verifies that the access_token has expired, it will return status 401

Agent Authorization API

● Definition of Agent Token API

Agent token is used for JSSDK and UISDK to request to obtain token

https://sg.sobot.io/tokens/agent

Request param:

Param	Type	Required	Description
responseType	String	Yes	Requested jwt type, currently available: token
appId	String	Yes	User's unique ID
currentTime	Long	Yes	Timestamp （millisecond）
sign	String	Yes	Signature, calculated as MD5(app_id+current_time+response_type+app_secret)
agentId	String	No	Agent id
agentNo	String	No	Agent work no.

Note: At least one of agentId and agentNumber must exist in the API params, and agentNumber is invalid when agentId exists. Request example

curl -X post https://sg.sobot.io/tokens/company -D
'{\
    "responseType":"token",\
    "appId":"b86fc8142f784bfb9215d45df64a17ea",\
    "currentTime":"1627462929415",\
    "sign":"fdf6066cfc12e73d7ebc571235c8be45",\
    "agentNo":"1008"
}'

Return when succeeded

{
"response_type":"token",
"access_token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0ODUxNDA5ODQsImlhdCI6MTQ4NTEzNzM4NCwiaXNzIjoiYWNtZS5jb20iLCJzdWIiOiIyOWFjMGMxOC0wYjRhLTQyY2YtODJmYy0wM2Q1NzAzMThhMWQiLCJhcHBsaWNhdGlvbklkIjoiNzkxMDM3MzQtOTdhYi00ZDFhLWFmMzctZTAwNmQwNWQyOTUyIiwicm9sZXMiOltdfQ.Mp0Pcwsz5VECK11Kf2ZZNF_SMKu5CgBeLN9ZOP04kZo",
"expires_in": 86400000,
"realm":"third",
"domain":"sobot"
}

Return when failed

{
  "errcode": 400,
  "error_desc":"invalid params"
}

● Use access_token

HTTP Authorization header should be added to all external Sobot APIs. Here is the example:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0ODUxNDA5ODQsImlhdCI6MTQ4NTEzNzM4NCwiaXNzIjoiYWNtZS5jb20iLCJzdWIiOiIyOWFjMGMxOC0wYjRhLTQyY2YtODJmYy0wM2Q1NzAzMThhMWQiLCJhcHBsaWNhdGlvbklkIjoiNzkxMDM3MzQtOTdhYi00ZDFhLWFmMzctZTAwNmQwNWQyOTUyIiwicm9sZXMiOltdfQ.Mp0Pcwsz5VECK11Kf2ZZNF_SMKu5CgBeLN9ZOP04kZo

● Error Code

Status	Message	Description
400	invalid params	Params with illegal token
401	Unauthorized	Invalid token
403	Forbidden	Illegal request resource

Company Authorization API

● Definition of Company Token API

Company token is used to access HTTP open API and request to obtain token

https://sg.sobot.io/tokens/company

Request param:

Param	Type	Required	Description
responseType	String	Yes	Requested jwt type, currently available: token
appId	String	Yes	User's unique ID
currentTime	Long	Yes	Timestamp （millisecond）
sign	String	Yes	Signature, calculated as MD5(app_id+current_time+response_type+app_secret)

Request example

curl -X post https://sg.sobot.io/tokens/company -D
'{\
    "responseType":"token",\
    "appId":"b86fc8142f784bfb9215d45df64a17ea",\
    "currentTime":"1627462929415",\
    "sign":"fdf6066cfc12e73d7ebc571235c8be45"\
}'

Return when succeeded

{
"response_type":"token",
"access_token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE0ODUxNDA5ODQsImlhdCI6MTQ4NTEzNzM4NCwiaXNzIjoiYWNtZS5jb20iLCJzdWIiOiIyOWFjMGMxOC0wYjRhLTQyY2YtODJmYy0wM2Q1NzAzMThhMWQiLCJhcHBsaWNhdGlvbklkIjoiNzkxMDM3MzQtOTdhYi00ZDFhLWFmMzctZTAwNmQwNWQyOTUyIiwicm9sZXMiOltdfQ.Mp0Pcwsz5VECK11Kf2ZZNF_SMKu5CgBeLN9ZOP04kZo",
"expires_in": 86400000,
"realm":"third",
"domain":"sobot"
}

Return when failed

{
  "code": 400,
  "error_desc":"invalid params"
}

Error Handling

Unified error handling

{
  "apiVersion": "6.2", // API version
  "status": "Failure", // Success or Failure
  "message": "Sorry, System is under maintenance.", // Prompt users with error messages; display in multiple languages via Accept-Language. Chinese by default
  "code": 500,  // http status code
  "reason": "error.message.label",  // Error message key label
  "kind": "MainCDRInfo",  // Entity types, here including MainCDRInfo and PartyCDRInfo
  "metaData": {
      "creatorId":"1f9ce5af91d8-1ecc12b03aa7a8755ad2",
      "creationTime": 1617173030902 ,
      "updateUserId":"44c8f4014e53c4677736c4c8c26a7c0d",
      "updatedTime": 1617173096236
  }
}