CDNetworks Documentation Cloud VoD Interface Authentication V3

Interface Authentication V3

Last update:2023-02-02 17:43:40

Interface authentication v3 is more secure than the other two authentications. The original two interface authentication methods can still be used, and it is recommended to use this authentication method.
Take Cloud VoD batch obtaining video list information interface as an example to illustrate the authentication method.

Request URL

Assemble the URI parameters of the specific interface behind

For example, the request URL to get the video list is as follows

Request Method

Support GET and POST requests

Individual interfaces support POST requests with content-type: application/json.

Common Parameters

This authentication method uses the following fields of request parameters:

Parameter Name            Types Is it requiredDescription
X-WS-AccessKeystring      Yes      Access Key ID (AccessKey ID). The corresponding AccessKey Secret is obtained through the AccessKey management interface of the console. Both the main account and the sub-account have different AccessKey IDs. The server will verify its authorization range, and the account can only operate on the data it has permission to operate.
X-WS-TimestampintYesTimestamp in seconds.
If the time differs from the server time by more than 5 minutes, the request is invalidated.
AuthorizationstringYesHTTP standard authentication header fields, for example:
"WS3-HMAC-SHA256 Credential=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa,SignedHeaders=content-type;host, Signature=fe5f80f77d5fa3beca038a248ff027d0445342fe2855ddc963176630326f1024"
where, -WS3
-HMAC-SHA256: this value is fixed at present;
- credential: signature certificate, aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa-WS-AccessKey is the X-;
- SignedHeaders: participation in the header information of the signature computation, content-type and the host is mandatory head;
- signature : signature digest. The verification certificate is calculated from all the parameters. For details, please refer to the signature calculation process (plus link) below. In the same X-WS-Timestamp, authorization is not allowed to be repeated within 5 minutes
content-TypestringYesThe type of data actually sent to the server. If it is called by a get request, then the parameter value is fixed at the beginning of "application/x-www-form-urlencoded"
hoststringYesRequest domain name, fixed as the requested domain name, ""

Signature (Sinature) calculation process

Algorithm overview

1, Signature=HexEncode(HMAC_SHA256(SecretKey, StringToSign ));
2, Stringtosign = Algorithm +\n+ Timestamp +\n+Hash.SHA256( CanonicalRequest )
3, CanonicalRequest =
Method +'\n'+
RequestURI +'\n'+
QueryString +'\n'+
CanonicalHeaders +'\n'+
SignedHeaders +'\n'+
4, HashedRequestPayload = Lowercase(HexEncode(Hash.SHA256( RequestPayload )))

1. Canonical Request (CanonicalRequest)

Splice the Canonical Request string (CanonicalRequest) in the following pseudo-code format:

CanonicalRequest =
    Method + '\n' +
    RequestURI + '\n' +
    QueryString + '\n' +
    CanonicalHeaders + '\n' +
    SignedHeaders + '\n' +

Field NameExplanation
MethodHTTP request method (GET, POST). In this example, the value is POST. Note that the characters here are uppercase.
RequestURIURI parameter, for the batch get video interface, the value of this parameter is /vod/videoManage/getVideoList
QueryStringThe query string in the URL that initiates the HTTP request. For POST requests, it is always an empty string "".
For GET requests, it is the string content after the question mark (?) in the URL, for example: "videoName=testVideoName&pageIndex=2&pageSize=5 ".
CanonicalHeadersThe specific information of the header involved in the signature includes at least two headers, host and content-type. You can also add a custom header to participate in the signature to improve the uniqueness and security of your own request.
Splicing rules:
1. The head key and value are converted to lowercase uniformly, and the leading and trailing spaces are removed, and spliced
according to the format of key:value\n; 2. Multiple headers are spliced according to the ascending ASCII order of the head key (lowercase). The calculation result of this example is "content-type: application/json; charset=utf-8\\n".
Note: The content-type must be consistent with the actual sent. Some programming language network libraries will automatically add the charset value even if it is not specified. If the signature is inconsistent with the sending, the server will return the signature verification failure.
SignedHeadersThe headers participating in the signature indicate which headers of this request participated in the signature, and correspond to the specific header information contained in CanonicalHeaders one-to-one. The content-type and host are mandatory headers.
Splicing rules:
1. Header keys are uniformly converted to lowercase;
2. Multiple header keys (lowercase) are spliced ​​in ascending ASCII order and separated by semicolons (;). This example is "content-type;host".
HashedRequestPayloadThe hash value of the request body (that is, the payload or body).
In such content-type: application / json transmission format parameters, the example is { "videoName": "a" , "pageSize": "5", "pageIndex": "2"} hash value;
as to Content -Type: application/x-www-form-urlencoded POST request method to pass parameters, the example is the hash value of "videoName=a&pageIndex=2&pageSize=5"; the
calculated pseudo code is Lowercase(HexEncode(Hash.SHA256(RequestPayload)) )), that is, SHA256 hash the HTTP request body, then hexadecimal encoding, and finally the encoded string is converted into lowercase letters.
For GET requests, RequestPayload is always an empty string.
The calculation result for this example is 135b13e1b15e3c836eab2ab9196a86e7bcdb7b68da27215175a65b89ade3587e.

According to the above rules, the CanonicalRequest string obtained in the example is as follows:


content-type:application/json; charset=utf-8


2. Join the string to be signed (StringToSign)

Concatenate the string to be signed in the following format:

StringToSign =

    Algorithm + \n +

    Timestamp + \n +


Field NameExplanation
AlgorithmThe signature algorithm is currently fixed as "WS3-HMAC-SHA256".
TimestampRequest timestamp, that is, the value of the public parameter X-WS-Timestamp in the request header, which is the current time UNIX timestamp, accurate to the second. In this example, the value is 1564645579
HashedCanonicalRequestThe hash value of the canonical request string spliced ​​in the foregoing steps is calculated as Lowercase(HexEncode(Hash.SHA256(CanonicalRequest))). The calculation result of this example is "16bc1b4d4e6818f5aec2a7273cb2c3d3e4831fd61c6510222b9bec19bffac646"

Note: Timestamp must be the current system time, and ensure that the system time and standard time are synchronized. If the difference is more than five minutes, it will fail. If it is not synchronized with the standard time for a long time, it may cause the request to fail after running for a period of time and return a signature expiration error.

According to the above rules, the string to be signed StringToSign obtained in the example is as follows:


3. Calculate the signature (Signature)

  1. Obtain the signing key, for example:
SecretKey = bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb

Field NameExplanation
SecretKeyOriginal AccessKey Secret
  1. Calculate the signature, the pseudo code is as follows:
Signature = HexEncode(HMAC\_SHA256(SecretKey, StringToSign))

4. Splicing Authorization

Splice Authorization in the following format:

Authorization =
    Algorithm + ' ' +
    'Credential=' + AccessKey + ', ' +
    'SignedHeaders=' + SignedHeaders + ', ' +
    'Signature=' + Signature

Field NameExplanation
AlgorithmThe signature method is fixed as "WS3-HMAC-SHA256".
AccessKeyThe AccessKey Secret in the key pair is obtained from the "User Center-AccessKey Management" page of the console. The value in this example is AKIDz8krbsJ5yKBZQpn74WFkmLPx3EXAMPLE.
SignedHeadersSee above, the header information involved in the signature. The value of this example is "content-type;host"
SignatureSignature value. The calculation result for this example is "72e494ea809ad7a8c8f7a4507b9bddcbaa8e581f516e8da2f66e2c5a96525168".

According to the above rules, the value obtained in the example is:

WS3-HMAC-SHA256 Credential=AKIDz8krbsJ5yKBZQpn74WFkmLPx3EXAMPLE, SignedHeaders=content-type;host, Signature=792dcb6d648a456a030c9c6683fa7bde2a31cb4c72cfeaa354da000adf7c288d

The final complete call information is as follows:

Authorization: WS3-HMAC-SHA256 Credential=AKIDz8krbsJ5yKBZQpn74WFkmLPx3EXAMPLE, SignedHeaders=content-type;host, Signature=792dcb6d648a456a030c9c6683fa7bde2a31cb4c72cfeaa354da000adf7c288d
Content-Type: application/json; charset=utf-8
X-WS-AccessKey: AKIDz8krbsJ5yKBZQpn74WFkmLPx3EXAMPLE
X-WS-Timestamp: 1564645579


General error code

Error CodeDescription
4001Authentication parameter error, please check whether all required parameters have passed values
4002X-WS-AccessKey parameter error, please check whether the key exists, whether there are fewer or more characters copied
4003X-WS-Timestamp parameter error, the time format is second-level timestamp
4004X-WS-Timestamp expires, and the time difference between the time when the server receives the request and the server receives the request must not exceed five minutes
4005host parameter error, please check
4006The content-type parameter is wrong, please check
4007Authentication failed, please check whether the parameters are correct
4008Authentication failed, please check whether the signature calculation is wrong, or the signature does not match the actual content sent, it may also be caused by an error in the key AccessKey Secret
4009The signature has been used, please regenerate the authentication parameters

curl example

content-type: application/json post request (recommended method)

curl -X POST 
-H "Authorization: WS3-HMAC-SHA256 Credential=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa, SignedHeaders=content-type;host, Signature=471d8f86cefa4fa2f929642207b6df8fe770e82e0df328f4f68af08c8b8a8029" 
-H "Content-Type: application/json; charset=utf-8" 
-H "Host:" 
-H "X-WS-Timestamp: 1564644606" 
-H "X-WS-AccessKey: aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" 
-d '{"videoName": "a","pageIndex":"2","pageSize":"5"}'

content-type: application/x-www-form-urlencoded post request

curl -X POST 
-H "Authorization: WS3-HMAC-SHA256 Credential=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa, SignedHeaders=content-type;host, Signature=37ea1014de0c90e83e733f8d19a5d3ae993896d34450c9f8cf8df5642c81339e" 
-H "Content-Type: application/x-www-form-urlencoded; charset=utf-8" 
-H "Host:" 
-H "X-WS-Timestamp: 1564644607" 
-H "X-WS-AccessKey: aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" 
-d 'videoName=a&pageIndex=2&pageSize=5'

get request
Note that the Content-Type in the get request is fixed in application/x-www-form-urlencoded format.

curl -X GET 
-H "Authorization: WS3-HMAC-SHA256 Credential=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa, SignedHeaders=content-type;host,     Signature=0b489e43c5cd2e52cbe0768a68c614a4211210a6d63b18ff65cc986f18e75aac" 
-H "Content-Type: application/x-www-form-urlencoded; charset=utf-8" 
-H "Host:" 
-H "X-WS-Timestamp: 1564644607" 
-H "X-WS-AccessKey: aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"

content-type: post request of multipart/form-data
Due to the complicated structure of the authorization parameter of the request, it needs to be generated in the code. Please refer to the following java code example.

java code example

The API connection can be used by quoting the tool class, and the until.jar package needs to be imported .

Detailed code example

import com.cnc.cloudv.util.auth.ApiAuthUtil;
import com.cnc.cloudv.util.httpclient.CloudvHttpResponse;

import java.util.HashMap;
import java.util.Map;

public class TestAuthUtil {
    private final static String ACCESS_KEY = "aaaaaaaaaaaaaaaaaaaaaaaaa";
    private final static String SECRET_KEY = "bbbbbbbbbbbbbbbbb";
    private final static String API_HOST = "";

    public static void main(String[] args) throws Exception {
        Map<String, String> customHeaderMap = new HashMap<String, String>(2);
        customHeaderMap.put("from", "test-authentification-sdk");
        String requestURI = "/vod/videoManage/getVideoList";

        String body = "{\"videoName\": \"测\",\"pageIndex\":\"2\",\"pageSize\":\"5\",\"format\": \"json\"}";
        CloudvHttpResponse cloudvHttpResponse = ApiAuthUtil.callPostJsonBodyRequest(API_HOST, ACCESS_KEY, SECRET_KEY, requestURI, customHeaderMap, body);
        String canonicalQueryString = "videoName=" +"测", "utf-8") + "&pageIndex=2&pageSize=5&format=json";
        cloudvHttpResponse = ApiAuthUtil.callGetRequest(API_HOST, ACCESS_KEY, SECRET_KEY, requestURI, customHeaderMap, canonicalQueryString);

        body = "videoName=" +"测", "utf-8") + "&pageIndex=2&pageSize=5&format=json";
        cloudvHttpResponse = ApiAuthUtil.callPostFormUrlencodedBodyRequest(API_HOST, ACCESS_KEY, SECRET_KEY, requestURI, customHeaderMap, body);
        Map<String, String> map = new HashMap<String, String>();
        map.put("videoName", "测");
        map.put("pageIndex", "2");
        map.put("pageSize", "5");
        map.put("format", "json");
        cloudvHttpResponse = ApiAuthUtil.callPostFormUrlencodedBodyRequest(API_HOST, ACCESS_KEY, SECRET_KEY, requestURI, customHeaderMap, map);



    public static void log(CloudvHttpResponse cloudvHttpResponse) throws Exception {
        System.out.println("返回结果是:" + cloudvHttpResponse + " , requestId = " + cloudvHttpResponse.getHeaders().get("X-WS-RequestId"));


Is the content of this document helpful to you?
I have suggestion
Submitted successfully! Thank you very much for your feedback, we will continue to strive to do better!