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：AKIDJ5yKBZQpn74WFkmLPx3gnPhESA
SecretKey：Gu5tcd98joQYCN3Cozk1qA
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
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):
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:
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.
