Authentication

Overview

All APIs mentioned on this site require stringent authentication. Please read the following sections carefully to understand how to perform the signature and authentication.

For all HTTP methods (GET, POST, PUT, DELETE), it is essential to include specific keys:

• Authorization
• Timestamp
• Nonce

with the correct values in the request header. Failure to do so will result in a response with the code 1011 or other non-zero codes.

K-V of Request Header

K-V stands for the key-value pairs of the request header. The following keys must be included in the request headers for each API:

Key	Description	Value Format
Authorization	Signature information	cbs:APPID:Signature
Timestamp	Request timestamp	The unit is seconds. Timezone must be set to UTC. For example, 2022-02-28 08:00:00 (UTC+0), the corresponding timestamp should be 1646035200
Nonce	Random seed	It is recommended that the nonce be different for each request, with a maximum length of 36 characters.

Notes:

Timestamp is the timestamp at the time of the request. Please avoid modifying the Timestamp value arbitrarily. The server will assess whether the request has expired based on whether the timestamp is more than 60 seconds away from the current time, helping prevent potential repeated attacks.

Authorization

The Authorization consists of the following three parts:

• cbs: Fixed prefix: simply use cbs.
• APPID: The APPID, obtained from Clobotics, is used to apply for all API requests.
• Signature: Utilize APPID and APPSECRET for symmetric encryption to sign the request. The steps for the Calculation of the Signature are outlined below.

Notes:

cbs, APPID, and Signature are concatenated with :. Ensure there are no spaces before or after the colons.

Calculation of the Signature

The formula for calculating the signature is as follows:

Signature = Base64(HMAC-SHA256(APPSECRET, StringToSign))

The StringToSign is the string that needs to be signed, and its construction method is as follows:

StringToSign = Method + "\n" +Content-MD5 + "\n" + Timestamp + "\n" + Nonce + "\n" + CanonicalizedResource

Notes:

\n represents a newline character, and the sequence of concatenation for Method, Content-MD5, etc. cannot be altered arbitrarily.

The significance of each part of StringToSign is as follows:

Name	Description
Method	The method of the HTTP request: GET, POST, PUT, and DELETE. All in uppercase.
Content-MD5	It is Base64(MD5(body)) of the request content, where body is the message body (request body) in the request. Please refer to Body Requirement
Timestamp	The timestamp at the time of the request. The value of the Timestamp key in the request header remains the same.
Nonce	Random seed. The value of the Nonce key in the request header remains the same.
CanonicalizedResource	The value of canonical resources. Please refer to Canonicalized Resource

Body Requirement

• When the request method is GET or DELETE, and there is no request body, Content-MD5 does not participate in the signature.
• When the request method is POST or PUT, please use the actual request body data. In the case of using the image upload API, Content-MD5 does not participate in the signature.
• MD5(body) refers to the byte stream obtained after MD5 calculation. There is no need for hex encoding after the MD5 calculation.

Canonicalized Resource

CanonicalizedResource indicates that to access the specification description of the URL, you need to concatenate the path and query parameters to generate a sub-resource string. The query parameters are sorted in ascending order based on the parameter name (A-Za-z), and "&" is used as a separator.

Let's take an example to illustrate how to generate the canonical resource value.

• Original request url

/api?status=COMPLETE&name=test_alert&callback=https%3A%2F%2Fwww.baidu.com%3Fquery%3Dchina

• The canonical resource value required for signing:

/api?callback=https://www.baidu.com?query=china&name=test_alert&status=COMPLETE

Notes:

• The calculation rules for CanonicalizedResource only dictate the signature to adhere to this specification, and there is no need to modify the original request URL.
• All parameter values (including non-English characters, URLs, special characters, etc.) should not be UrlEncoded when used in the signature. Otherwise, the server signature verification will fail.

Sample Request with Authorization

Retrive the right OpenAPI application

Suppose we have an APPID and APPSECRET pair as:

• APPID: 85206f97-2f4f-4b6e-8830-f3f4ec6fd6ae
• APPSECRET: c6ae8924a68a5d839947a7885894dfe4

POST、PUT Sample

The signatures for POST and PUT requests are similar. The following example illustrates the POST request:

POST http://127.0.0.1:8080/ir/recongize?name=hk&callback=https%3A%2F%2Fwww.baidu.com%3Fquery%3Dchina
Content-Type:application/json
Nonce:sweewew
Timestamp:1666764711
Authorization：cbs:85206f97-2f4f-4b6e-8830-f3f4ec6fd6ae:OaUMtmkO2pxAuP/iU3hj8+Bn4FosdVyu8eflY8mMcyE=

With the request body as follows:

{"request_id":"9177er67378273888287321","image_url":"https://f-dev.clobotics.cn/4/0040ca4d85f5e5ef7354102f486ef843.jpg","scene_type":"104","ext_info":"this is a test"}

1. Calculate the body's Content-MD5

Content-MD5=ilHp6H9FaX49IFrwOj/TDw==

2. Then get StringToSign:

POST
ilHp6H9FaX49IFrwOj/TDw==
1676764711
ererere
/ir/recongize?callback=https://www.baidu.com?query=china&name=hk

Notes:

callback and name parameters are sorted in lexicographical order, and the value for the callback parameter is used without UrlEncode.

3. Calculate Signature by Base64(HMAC-SHA256(APPSECRET, StringToSign))

Signature=OaUMtmkO2pxAuP/iU3hj8+Bn4FosdVyu8eflY8mMcyE=

4. Obtain Authorization

Authorization=cbs:85206f97-2f4f-4b6e-8830-f3f4ec6fd6ae:OaUMtmkO2pxAuP/iU3hj8+Bn4FosdVyu8eflY8mMcyE=

GET、 DELETE Sample

The signatures for GET and DELETE requests are similar. The following example illustrates the GET request:

GET http://127.0.0.1:8080/ir/recognize/result/7177er67378273888287321
Nonce:ererere
Timestamp:1666764711
Authorization: cbs:85206f97-2f4f-4b6e-8830-f3f4ec6fd6ae:7qyLW5QVHcgUC8nHwwtJWTxAGn1TDA5TQigoLngWo+o=

1. Get StringToSign

GET
1676764711
ererere
/ir/recognize/result/7177er67378273888287321

Notes:

For GET and DELETE requests, there is no need to calculate Content-MD5.

2. Calculate Signature by Base64(HMAC-SHA256(APPSECRET, StringToSign))

Signature=7qyLW5QVHcgUC8nHwwtJWTxAGn1TDA5TQigoLngWo+o=

3. Obtain Authorization

Authorization=cbs:85206f97-2f4f-4b6e-8830-f3f4ec6fd6ae:7qyLW5QVHcgUC8nHwwtJWTxAGn1TDA5TQigoLngWo+o=