Welcome to our product and service offerings. You can use the APIs and examples described in this document to perform operations on our products and services. To use the APIs, ensure that you have activated your AccessKey and fully understand the product documentation and API usage agreement before calling these APIs.
API calls are made by sending HTTP(s) requests to the API service endpoint to create, retrieve, modify, or delete resources, with the required request parameters included according to the API documentation. The system returns the processing result based on how the request is handled. To facilitate issue tracking and communication, our platform assigns an ID to each request/task and adds the x-cnc-request-id field to the response header to return the request ID to the customer. Please note that the JSON or XML fields in API responses may be expanded with new JSON or XML fields based on the existing structure as features evolve. Developers must parse these fields according to JSON and XML specifications instead of parsing them based on specific strings. Our platform limits the request frequency for each customer account. By default, the number of requests must not exceed 300 every 5 minutes. A recommended frequency of 30 requests/5min applies to each account for an individual API. If you have special requirements, contact our platform API team.
Communication Protocol
Requests can be sent over HTTP or HTTPS channels. For enhanced security, we recommend using HTTPS to send requests.
Request Methods
Supports POST, GET, PUT, DELETE, and other methods.
Request Parameters:
| Request Header | Type | Required | Description |
|---|---|---|---|
| x-cnc-accessKey | string | Required | |
| x-cnc-timestamp | int | Required | A timestamp in seconds. If the difference between this timestamp and the server time exceeds 5 minutes, the request becomes invalid. |
| x-cnc-auth-method | string | Required | API authentication method. When using AccessKey authentication, this header is required and its value must be AKSK. |
| Authorization | string | Required | HTTP standard authentication header field, for example: “CNC-HMAC-SHA256 Credential=qiVc3ieau1BlosMghhauAHnBcjd2ceqcCC4Z, SignedHeaders=content-type;host, Signature=5b73ebca11a738be44caa52179af87b4dccac4035fa363ebda4b8328eca3d21f”其中，- CNC-HMAC-SHA256: Signature method, currently fixed to this value; - Credential: Signature credential, qiVc3ieau1BlosMghhauAHnBcjd2ceqcCC4Z is x-cnc-accessKey; - SignedHeaders: Header information involved in signature calculation, where content-type and host are required headers; - Signature: Signature digest. The verification credential is calculated from all parameters. For details, see the signature calculation process below (add link). For the same x-cnc-timestamp, Authorization cannot be repeated within 5 minutes. |
| content-Type | string | Required | The data type actually sent to the server. |
| host | string | Required | Request domain, the domain for API requests. |
Response Parameters:
| Response Headers | Description |
|---|---|
| Accept | MIME types acceptable to the browser |
| Content-Type | The MIME type of the requested resource. Note: This is required when using the POST or PUT method. |
| Date | The format must comply with RFC 1123, such as Thu, 17 May 2012 19:37:58 GMT |
Our platform authenticates every API request. Therefore, regardless of whether the request is submitted over HTTP or HTTPS, authentication information must be included in the request.
When calling an API, users must include {x-cnc-accessKey}, {x-cnc-timestamp}, {Authorization}, {content-Type}, and {host} in the request headers.
Our platform calculates the Authorization value based on the value of the request header parameter and compares it with {Authorization} in the original request header. If the verification succeeds, subsequent processing continues; otherwise, the corresponding error message is returned to the caller.
Authorization = Algorithm + ’ ’ + ‘Credential=’ + AccessKey + ', ’ + ‘SignedHeaders=’ + SignedHeaders + ', ’ + ‘Signature=’ + Signature
Field Name | Description |
|---|---|
| Algorithm | The signature method, fixed as “CNC-HMAC-SHA256”. |
| AccessKey | The AccessKey ID in the key pair, which can be obtained from the “AccessKey Management” page in the console. The value in this example is qiVc3ieau1BlosMghhauAHnBcjd2ceqcCC4Z. |
| SignedHeaders | See below for the headers included in the signature. The value in this example is “content-type;host” |
| Signature | The signature value. The calculated result in this example is “5b73ebca11a738be44caa52179af87b4dccac4035fa363ebda4b8328eca3d21f”. |
Signature Calculation Process
Signature=HexEncode(HMAC_SHA256(SecretKey, StringToSign));
Stringtosign=Algorithm+\n+Timestamp+\n+Hash.SHA256(CanonicalRequest)
CanonicalRequest=
Method+’\n’+
RequestURI+’\n’+
QueryString+’\n’+
CanonicalHeaders+’\n’+
SignedHeaders+’\n’+
HashedRequestPayload
HashedRequestPayload= Lowercase(HexEncode(Hash.SHA256(RequestPayload)))
Concatenate the canonical request (CanonicalRequest) according to the following pseudocode format：
CanonicalRequest =
Method + ‘\n’ +
RequestURI + ‘\n’ +
QueryString + ‘\n’ +
CanonicalHeaders + ‘\n’ +
SignedHeaders + ‘\n’ +
HashedRequestPayload
| Field Name | Description |
|---|---|
| Method | HTTP request method (GET, POST). The value in this example is GET. Note that the characters are uppercase. |
| RequestURI | URI parameter, such as /api/aksk/test. |
| Query String | The query string in the URL used to initiate the HTTP request. For POST requests, this is always the empty string ""; for GET requests, it is the string after the question mark (?) in the URL. This part must be decoded, for example: decode("test=test&a=a"). |
| Canonical Headers | The specific header information involved in signing. At a minimum, the host and content-type headers must be included. Custom headers may also be added to the signature to improve the uniqueness and security of your requests.Concatenation rules: 1. Convert the header key and value to lowercase, remove leading and trailing spaces, and concatenate them in the format key:value\n;2. Concatenate multiple headers in ascending ASCII order by the header key (in lowercase). The result calculated for this example is: text<br>content-type:application/json<br>host:openapi.tokencube.net<br>Note: content-type must match the content actually sent. Some programming language networking libraries automatically add a charset value even when it is not specified. If the value used during signing is inconsistent with the value sent, the server will return a signature verification failure. |
| Signed Headers | The headers involved in signing, indicating which headers are included in the signature for this request. These headers correspond one-to-one with the specific header information contained in CanonicalHeaders. The content-type and host headers are required.Concatenation rules: 1. Convert the header keys to lowercase; 2. Concatenate multiple header keys (in lowercase) in ascending ASCII order, separating them with semicolons ( ;).For this example: content-type;host. |
| Hashed Request Payload | The hash value of the request body (that is, the payload or body). If parameters are passed using the content-type: application/json format, this is the hash value of {"test":"body"};If parameters are passed in a POST request using Content-Type: application/x-www-form-urlencoded, this is the hash value of "test=body".The pseudocode is: Lowercase(HexEncode(Hash.SHA256(RequestPayload))), which means calculating the SHA256 hash of the HTTP request body, performing hexadecimal encoding, and then converting the encoded string to lowercase.For GET requests, RequestPayload is always an empty string.The result calculated for this example is: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855. |
According to the rules above, the CanonicalRequest obtained in the example is as follows:
GET
/api/aksk/test
test=test&a=a
content-type:application/json
host:openapi.tokencube.net
content-type;host
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
2. Concatenate the StringToSign
Concatenate the StringToSign in the following format:
StringToSign = Algorithm + \n + Timestamp + \n + HashedCanonicalRequest
| Field Name | Description |
|---|---|
| Algorithm | The signing algorithm, which is currently fixed as CNC-HMAC-SHA256. |
| Timestamp | The request timestamp, which is the value of the common request header parameter x-cnc-timestamp. Use the current UNIX timestamp, accurate to the second. In this example, the value is 1631239486. |
| HashedCanonicalRequest | The hash of the canonical request string concatenated in the preceding step. The pseudocode for calculating it is Lowercase(HexEncode(Hash.SHA256(CanonicalRequest))). The calculation result in this example is: 990b65d70886cbf13eef1a6bffdb695b53ea74e7ab150d77efc64acc464443e0. |
According to the rules above, the StringToSign to be signed in the example is as follows:
CNC-HMAC-SHA256
1631239486
990b65d70886cbf13eef1a6bffdb695b53ea74e7ab150d77efc64acc464443e0
3. Calculate Signature(Signature)
1）Obtain the signing key, for example：
SecretKey = test
| Field Name | Description |
|---|---|
| SecretKey | Original AccessKey Secret |
2）Calculate the signature, with the pseudocode as follows：
Signature = HexEncode(HMAC_SHA256(SecretKey, StringToSign))
According to the rules above, the value obtained in the example is:
CNC-HMAC-SHA256 Credential=qiVc3ieau1BlosMghhauAHnBcjd2ceqcCC4Z, SignedHeaders=content-type;host, Signature=1b81bc8fec1058e2df8e5aa7526be348311d3fc97ab428464d833cf23cceb273
The final complete call information is as follows:
GET https://openapi.tokencube.net/api/aksk/test?test=test&a=a
Authorization: CNC-HMAC-SHA256 Credential=qiVc3ieau1BlosMghhauAHnBcjd2ceqcCC4Z, SignedHeaders=content-type;host, Signature=1b81bc8fec1058e2df8e5aa7526be348311d3fc97ab428464d833cf23cceb273
Content-Type: application/json;
Host: openapi.tokencube.net
x-cnc-accessKey: qiVc3ieau1BlosMghhauAHnBcjd2ceqcCC4Z
x-cnc-timestamp: 1631239486
Successful Result
You can directly provide examples of successful results, such as separate JSON and XML examples.
Codeblock 7 JSON Example
HTTP/1.1 {2xx}
Date: Fri, 26 Oct 2012 06:33:26 GMT
Content-Type: application/xml;charset=utf-8
x-cnc-request-id:{id string auto generated by cloud server} /* This Is the Globally Unique Request ID */
{
/* Return Result Data */
}
Codeblock 8 XML Example
HTTP/1.1 {2xx}
Date: Fri, 26 Oct 2012 06:33:26 GMT
Content-Type: application/xml;charset=utf-8
x-cnc-request-id:{id string auto generated by cloud server} /* This is a globally unique request ID */
<?xml version="1.0" encoding="UTF-8"?>
<!—Root node of the result-->
<!—Return result data-->
</!—Root node of the result-->
Error Response
If an API call fails, no result data will be returned. The caller can identify the cause of the error based on the “error code”. When a call fails, the HTTP request returns a 4xx or 5xx HTTP status code. The response body contains the specific error code and error message. In addition, the request header contains a globally unique request ID: RequestId. If the caller cannot determine the cause of the error, they can contact the relevant technical support personnel and provide the RequestId so that we can help resolve the issue as soon as possible.
Codeblock 9 JSON Example
HTTP/1.1 {4xx or 5xx}{error such as Access Denied or InternalError}
Date: Fri, 26 Oct 2012 06:33:26 GMT
Content-Type: application/xml;charset=utf-8
x-cnc-request-id:{id string auto generated by cloud server} /* This Is a Globally Unique request ID */
{
"code": "{the error code, like MissingDateHeader}",
"message": "{description, like Authorized request must have a Date or x-cnc-date header }"
}
Codeblock 10 XML Example
HTTP/1.1 {4xx or 5xx}{error such as Access Denied or InternalError}
Date: Fri, 26 Oct 2012 06:33:26 GMT
Content-Type: application/xml;charset=utf-8
x-cnc-request-id:{id string auto generated by cloud server} /* This Is a Globally Unique Request ID */
<?xml version="1.0" encoding="UTF-8"?>
<response>
<code>{the error code, like MissingDateHeader}</code>
<message>{description, like Authorized request must have a Date or x-cnc-date header}</message>
</response>
Public Authentication Error Codes
| HTTP Status Code | Code | Message | Semantics |
|---|---|---|---|
| 401 | WPLUS_InvalidHTTPAuthHeader | The HTTP Authorization header is invalid. | No account information was provided, or the account information format is invalid. |
| 403 | WPLUS_RequestTokenNotExistError | The request token does not exist or has expired | The requested token has exceeded its configured validity period |
| 431 | WPLUS_MatchApiNone | No suitable API was found for the request. | No matching API was found in the requested URL. |
| 432 | WPLUS_ApiPrivilegeError | The account being used is not authorized to access this API. | The account currently being used does not have permission to access the API |
| 434 | WPLUS_RequestExpired | The request has expired. | The date in the request header is too old (the date in the request’s date header must not be significantly earlier than the time when the request was initiated; otherwise, the request is considered stolen) |
| 435 | WPLUS_AccountTooFrequence | The account’s request frequency has reached the threshold. | The request frequency for the account initiating the request has reached the threshold |
| 436 | WPLUS_IPTooFrequence | The IP’s request frequency has reached the threshold. | The request frequency for the originating IP has reached the threshold |
| 437 | WPLUS_AccountCapacityFull | The account’s bandwidth usage has reached the threshold. | The bandwidth usage of the account initiating the request has reached the threshold |
| 438 | WPLUS_APiTooFrequence | The API request frequency has reached the threshold. | The request frequency for the API has reached the threshold |
| 439 | WPLUS_APiCapacityFull | The API’s bandwidth usage has reached the threshold. | The bandwidth usage of the API invoked by the request has reached the threshold |
| 440 | WPLUS_AccountWhitelist | The remote IP does not exist in the account’s whitelist. | The originating IP is not included in the whitelist configured for the account |
| 441 | WPLUS_ApiWhitelist | The remote IP does not exist in the API’s whitelist. | The originating IP is not included in the whitelist configured for the API |
| 443 | WPLUS_ApiUnactive | The invoked API is inactive. | The requested API is in an inactive state |
| 446 | WPLUS_AccountApiTooFrequence | The Account’s Calls to the Specified API Are Too Frequent. | The specified account is accessing the specified API too frequently and has exceeded the frequency threshold. |
| 447 | WPLUS_APiTooConcurrent | The API Calls Have Exceeded the Concurrency Threshold. | The specified API is being called too frequently and has exceeded the threshold. |
| 448 | WPLUS_AccountTooConcurrent | The Account’s Concurrent Calls Have Reached the Concurrency Threshold. | The number of concurrent calls for the specified account has reached the concurrency threshold, where concurrency is defined as the number of calls for this account that are currently being processed (requests have been received but responses have not yet been returned). |
| 449 | WPLUS_AccountApiTooConcurrent | The Account’s Calls to the Specified API Have Exceeded the Concurrency Threshold. | The specified account is calling the specified API too frequently and has exceeded the limit. |
| 450 | WPLUS_DateError | The Date Is Invalid. | The request does not include a date header, or the header information is invalid. |
| 453 | WPLUS_HystrixSocketConnectTimeout | The Hystrix Socket Connection Timed Out. | The request timed out. |
| 462 | WPLUS_AuthorizationError | Authorization Failed. Please Check the Signature and AccessKey. | Authorization failed. Please check the AK/SK. |
| 501 | WPLUS_SystemError | System Error. | An internal system error occurred. |
| 503 | WPLUS_InvokeBackendFail | Failed to Invoke the Backend. | An exception occurred while calling a core internal system service. Please try again later or contact Technical Support. |
| 530 | WPLUS_InvalidArgument | An Exception Occurred While Reading the Body (InputStream) from HttpServletRequest. | An exception occurred while retrieving the body from HttpServletRequest. |
| 533 | WPLUS_CollectAgentMakeDirError | collectAgent call error:can not make folder. | CollectAgent failed to create a folder. |
| 534 | WPLUS_CollectAgentMakeFileError | collectAgent call error:can not make file. | CollectAgent failed to create a file. |
| 535 | WPLUS_RunShellError | run shell error. | An error occurred while executing the shell. |
| 537 | WPLUS_ProcessorHttpJobInvokerCallServiceError | We encountered an internal error in CommonJobInvoker when calling Netty. Please try again. | An exception occurred when the processor called an HTTP-type backend; this status code can only occur when calling an HTTP-type API. |
| 555 | WPLUS_HystrixSocketConnectError | hystrix socket connect error! | An exception occurred while the internal thread pool management tool Hystrix was connecting to a backend service component. |
Our company is committed to providing customers with high-quality services. In response to customer needs, we have encapsulated a series of CDN-related APIs. Thank you very much for trusting and using the APIs encapsulated by our company. APIs are convenient tools for customers to perform operations, maintenance, and queries. While providing convenience, they may also introduce certain uncontrollable risks for both parties. Therefore, based on the current scale of customers’ use of the CNC API, customers must agree to the following Terms of Use:
In this agreement, “API” refers to the Application Programming Interface (API) provided to you by our platform. After programming, you can use this Application Programming Interface to access the CDN-related operational services provided by our platform.
1.API Usage
1.1. We shall independently determine whether you are eligible to obtain an API usage license; that is, after our platform grants you an API key, you obtain a personal, free of charge, non-transferable, non-sublicensable, and non-exclusive license to use the API granted by our platform, enabling you to obtain the cloud services provided by our platform through the API。
1.2. Your number of accesses to our platform’s API and the volume of access data shall remain within the limits specified by our platform. If our platform discovers that you are attempting to exceed or circumvent these limits, your API access may be temporarily or permanently suspended。
1.3. You understand and agree that our platform only provides application programming interfaces, and you shall develop programs independently to call the services provided by our platform according to your needs. Our platform assumes no responsibility for your programming process or the results of applying your programs。
1.4 If our API interfaces need to be adjusted, please cooperate with the adjustment after receiving our notification and respond to the adjustment within 6 months。
1.5. If the APIs used by the customer threaten our company’s internal public systems, our company has the right to impose rate limiting on the APIs (with prior notification). If the use of the APIs is determined to be seriously malicious, we may even disable the customer’s access to the APIs；
1.6. If the customer adds too many unnecessary domains and there are many domains that have not generated traffic for a long time (which are determined to be valueless domains), the customer must clean them up independently, because the performance of the query interface will decrease as the number of domains increases。
1.7. The APIs are developed for the convenience of customers. Any faults in API calls do not affect CDN services that are already being accelerated, and therefore do not fall within the scope of CDN acceleration quality. They may not be used as a basis for determining that CDN acceleration is unavailable or as a basis for making claims；
2.1. You may not modify, translate, adapt, rent, sublicense, disseminate over information networks, or transfer the application interfaces provided by our platform, nor may you reverse engineer, decompile, or attempt to discover the source code of the application interfaces provided by our platform by any other means (unless expressly permitted by our platform)；
2.2. Engaging in any conduct that compromises or attempts to compromise network security (including but not limited to phishing, hacking, cyber fraud, or containing or being suspected of disseminating viruses, Trojans, or malicious code on websites or hosting spaces, as well as conducting suspected attacks against other websites or servers through virtual servers, such as scanning, sniffing, ARP spoofing, DOS, etc.);
2.3. Engaging in any conduct that changes or attempts to change the system configurations provided by our platform or compromises system security;
2.4. Failing to comply with these usage specifications or the requirements and announcements regarding the API displayed by our platform on the relevant pages, or infringing upon the rights of our platform or any third party;
2.5. Any other conduct that violates applicable laws and regulations.
3.1.If your use of the API must be interrupted or suspended due to the maintenance or upgrade of servers or systems related to our platform, our platform will provide advance notice whenever possible。
3.2.The data relating to your service calls through the API shall be subject to the data recorded in the backend of our platform。
4.Warranties
You understand and agree that, during the free period, our platform makes no warranties regarding any errors or vulnerabilities in the API。Your use of our platform’s API is based on your own judgment and is undertaken at your own risk, and you shall bear all losses arising from your use of our platform’s API。
5.Termination
You shall ensure that your use of our Platform’s API complies with the requirements of this Specification and applicable national laws and regulations, and shall not harm the interests of our Platform. If any of the following circumstances occurs, our Platform shall have the right to suspend or terminate your use of the API at any time:
5.1. The personal information or other information you provide is untrue, false, or unlawful;
5.2. Your use of our Platform’s API violates any provision of applicable national laws and regulations, this Specification, or the rules and announcements regarding the API displayed by our Platform on the relevant pages;
5.3. Our Platform, based on its independent judgment, determines that your use of the API does not comply with the requirements of our Platform;
5.4. Notwithstanding the foregoing, our Platform reserves the right to modify, suspend, or terminate the provision of the Service at any time without prior notice to you.
You and our Platform shall each be responsible for keeping the other party’s Confidential Information confidential, unless disclosure is required by competent national administrative, judicial, or other authorities, or the information has entered the public domain.
7.1. By using our Platform’s API, you agree to comply with these Terms of Use. Our Platform reserves the right to revise these Terms at any time and will notify you in advance. Once these Terms are changed, our Platform will publish the revised Terms and indicate the changes. You understand and agree that if you use the API services after the Terms have been revised, our Platform will deem your use to constitute acceptance of the revised Terms. If you do not accept the revisions, you must stop using the API.
7.2. Our Platform currently provides the API to you free of charge, but reserves the right to charge fees for it in the future. In such event, our Platform will publish the applicable charging policies and rules by issuing an announcement on the website or posting a notice in an appropriate section of the website. If you wish to continue using our Platform’s API, you must pay the service fees in accordance with the charging policies and rules published by our Platform at that time, and comply with the API terms of use, specifications, and procedures then in effect.
7.3. These Terms of Use shall be governed by the laws of the People’s Republic of China. If any dispute arises during the performance of these Terms of Service, both parties shall promptly resolve it through consultation. If consultation fails, either party may directly file a lawsuit with the Xuhui District People’s Court of Shanghai.