tencent cloud

TencentCloud API authenticates each access request, i.e., each request needs to include authentication information (Signature) in the common parameters to verify the identity of the requester. The Signature is generated by the security credentials which consist of SecretId and SecretKey. If you don't have the security credentials yet, go to the TencentCloud API Key page to apply for them; otherwise, you cannot call the TencentCloud API.

Applying for Security Credentials

Before using TencentCloud API for the first time, go to the Tencent Cloud Console -> API Key Management page to apply for security credentials. Security credentials consist of a SecretId and a SecretKey.

• SecretId is used to identify the API requester.
• SecretKey is used to encrypt the strings to create a signature so that Tencent Cloud server can validate the identity of the requester.

Note：

API key is an important identity credential for making Tencent Cloud API request. With APIs, you can access and manage the resources under your Tencent Cloud account. For the security of your assets and services, store your keys safely, change them regularly, and delete old keys promptly when a new one is created.

How to apply for security credentials

1. Log in to the Tencent Cloud Console and access the API Key Management page.
2. On the API Key Management page, click Create Key to create a SecretId/SecretKey pair.

Note：

• A developer account can have up to two SecretId/SecretKey pairs.
• A developer can add a QQ account as a sub-user and use it to apply for different security credentials on the console for various login user.
• A sub-user can only call certain specified TencentCloud APIs with their security credentials.

Generating a Signature String

After obtaining the security credentials (SecretId and SecretKey), you can generate a signature as follows:

Assume that the SecretId and SecretKey are:
SecretId：AKID****J5yKBZQpn74WFkmLPx3gnPhESA
SecretKey：Gu5t****cd98joQYCN3Cozk1qA

Note：

This is just an example. You need to use your own SecretId and SecretKey in actual operations.

Take the DescribeInstances API to query the list of CVM instances as an example. When you call this API, the request parameters may be as follows:

Parameter Description	Value
Action	Action name
SecretId	Key ID
Timestamp	Current timestamp
Nonce	Random positive integer
Region	Region where the instance resides
SignatureMethod	Signature method
InstanceIds.0	ID of the instance to query

1. Sorting parameters

First, sort all request parameters by parameter name in ascending lexicographical order, just like sorting words in a dictionary in ascending alphabetical order or numerical order. That is, sort the parameters by their first letters, then by their second letters if their first letters are the same, and so on. You can do this with the aid of sorting functions in programming languages, such as the ksort function in PHP. The sorting results of the above sample parameters are as follows:

{
    "Action" : "DescribeInstances",
    "InstanceIds.0" : "ins-09dx****",
    "Nonce" : "11886",
    "Region" : "ap-guangzhou",
    "SecretId" : "AKID****J5yKBZQpn74WFkmLPx3gnPhESA",
    "SignatureMethod" : "HmacSHA256",
    "Timestamp" : "1465185768"
}

You can use any other programming languages as long as the sorted parameters are the same as these in this example.

2. Concatenating a request string

This step generates a request string.
Format the request parameters sorted in the previous step into the form of "parameter name"="parameter value". For example, if the value of Action is "DescribeInstances", the parameter is formatted into Action=DescribeInstances.

Note：

• "Parameter value" is the original value instead of the URL-encoded value.
• Replace the underscore (if any) in the Key of an input parameter with a ., while maintain the underscore in the Value. For example, Placement_Zone=CN_GUANGZHOU should be converted to Placement.Zone=CN_GUANGZHOU.

Then, concatenate the formatted parameters with "&". The resulting request string is as follows (ignore the line breaks here):

Action=DescribeInstances
&InstanceIds.0=ins-09dx****
&Nonce=11886
&Region=ap-guangzhou
&SecretId=AKID****J5yKBZQpn74WFkmLPx3gnPhESA
&SignatureMethod=HmacSHA256
&Timestamp=1465185768

3. Concatenating the original signature string

This step generates an original signature string.
Construct a signature string in the format of

Note：

request method + request CVM + request path + ? + request string

Description of parameters:
Request method: both POST and GET methods are supported. This example uses the GET request method.

• Request CVM: the domain name of the request, which varies by the product or product module to which the API belongs. For example, the request domain name for the DescribeInstances API used to query the CVM instance list is: cvm.api.qcloud.com. For more information, see the instructions of the specific API.
• Request path: a fixed path for requesting TencentCloud APIs. For example, the request path for Tencent Cloud CVM is always /v2/index.php.
• Request string: the request string generated in the previous step.

The concatenation result of the example is as follows (ignore the line breaks here):

GETcvm.api.qcloud.com/v2/index.php?Action=DescribeInstances
&InstanceIds.0=ins-09dx****
&Nonce=11886
&Region=ap-guangzhou
&SecretId=AKID****J5yKBZQpn74WFkmLPx3gnPhESA
&SignatureMethod=HmacSHA256
&Timestamp=1465185768

4. Generating a signature string

This step generates a signature string.

Note：

There are two ways to calculate a signature: HmacSHA256 and HmacSHA1. The signature string will be generated based on the specified signature algorithm (i.e., the SignatureMethod parameter). The HmacSHA256 algorithm will be used if you specify SignatureMethod to “HmacSHA256”; otherwise, HmacSHA1 will be used.

First, use the signature algorithm (HmacSHA256 or HmacSHA1) to sign the original signature string obtained in the previous step, and then encode the generated signature using Base64 to get the final signature.

In this example, the PHP programming language is used to calculate the signature string with HmacSHA256. You can use any other programming languages as long as the resulting signature is the same as the one in this example. The sample code is shown as follows:

$secretKey = 'Gu5t9xGARNpq86cd98joQYCN3Coz****';
$srcStr = 'GETcvm.api.qcloud.com/v2/index.php?Action=DescribeInstances&InstanceIds.0=ins-09dx****&Nonce=11886&Region=ap-guangzhou&SecretId=AKID****J5yKBZQpn74WFkmLPx3gnPhESA&SignatureMethod=HmacSHA256&Timestamp=1465185768';
$signStr = base64_encode(hash_hmac('sha256', $srcStr, $secretKey, true));
echo $signStr;

The final signature string is:

0EEm/HtGRr/VJXT****YMth1Bzm3lLHz5RCDv1GdM8s=

Similarly, if you use the HmacSHA1 signature algorithm, the code to generate the signature string is as follows:

$secretKey = 'Gu5t9xGARNpq86cd98joQYCN3Coz****';
$srcStr = 'GETcvm.api.qcloud.com/v2/index.php?Action=DescribeInstances&InstanceIds.0=ins-09dx****&Nonce=11886&Region=ap-guangzhou&SecretId=AKID****J5yKBZQpn74WFkmLPx3gnPhESA&SignatureMethod=HmacSHA1&Timestamp=1465185768';
$signStr = base64_encode(hash_hmac('sha1', $srcStr, $secretKey, true));
echo $signStr;

The final signature string is as follows:

****Y6nj****8ciqbPl5Qe+Oru4=

Encoding a Signature String

The generated signature string cannot be directly used as a request parameter and must be URL encoded.
For example, the signature string 0EEm/HtGRr/VJXT****YMth1Bzm3lLHz5RCDv1GdM8s= generated in the previous step should be encoded to 0EEm%2FHtGRr%2FVJXT****YMth1Bzm3lLHz5RCDv1GdM8s%3D. Therefore, the resulting request parameter for the Signature is 0EEm%2FHtGRr%2FVJXT****YMth1Bzm3lLHz5RCDv1GdM8s%3D, which will be used to generate the final request URL.

Note：

If you are sending a GET request, all parameters in the request need to be URL-encoded. Please note that network libraries of some programming languages automatically URL encode all parameters, in which case there is no need to URL encode the signature string; otherwise, two rounds of URL encoding will cause the signature verification to fail.

Authentication Failures

The following errors may occur when authentication fails:

Error Code	Error Type	Error Description
4100	Identity verification failed	Identity verification failed. Please make sure that the Signature parameter added to your request is calculated correctly (refer to the preceding steps) and URL encoded.
4101	Unauthorized operation	The sub-user is not authorized to call this API. Please contact the developer for authorization. For more information, see Authorization Policy.
4102	Unauthorized operation	You are not authorized to access resources used by this API. Check the relevant resource IDs in the message field and contact the developer for authorization. For more information, see Authorization Policy.
4103	Unsupported operation	The sub-user's SecretId cannot be used to call this API. Only the developer account has access to this API
4104	SecretId does not exist	The SecretId does not exist or the status of SecretKey is incorrect. Please make sure that the API key is valid and enabled
4110	Authentication failed	Permission verification failed. Please make sure that you have the permission to access the resources
4500	Replay attack error	The Nonce parameter must be unique, and the difference between Timestamp and Tencent server time should be within two hours.