please select
Features & Server APIs
  • On-Cloud Recording
  • Relay to CDN
  • RTMP Streaming with TRTC
  • Event Callbacks
    • Room&Media Callbacks
    • Relay to CDN Callback
    • Cloud Recording Callback
    • Verify Signature Example
  • Sending and Receiving Messages
  • Access Management
    • Overview
    • Manageable Resources and Actions
    • Preset Policies
    • Custom Policies
  • Enabling Advanced Permission Control
  • How to push stream to TRTC room with OBS WHIP
  • Server APIs
    • API Category
    • History
    • Making API Request
      • Request Structure
      • Common Params
      • Signature v3
      • Signature
      • Responses
    • Room Management APIs
      • SetUserBlockedByStrRoomId
      • SetUserBlocked
      • RemoveUser
      • DismissRoom
      • RemoveUserByStrRoomId
      • DismissRoomByStrRoomId
    • Call Quality Monitoring APIs
      • DescribeRoomInfo
      • DescribeUserEvent
      • DescribeCallDetailInfo
      • DescribeUserInfo
      • DescribeScaleInfo
    • Pull Stream Relay Related Interface
      • StartStreamIngest
      • StopStreamIngest
      • DescribeStreamIngest
    • On-cloud Recording APIs
      • CreateCloudRecording
      • DescribeCloudRecording
      • ModifyCloudRecording
      • DeleteCloudRecording
    • Stream Mixing and Relay APIs
      • UpdatePublishCdnStream
      • StartPublishCdnStream
      • StopPublishCdnStream
    • Usage Statistics APIs
      • DescribeTrtcUsage
      • DescribeRecordingUsage
      • DescribeMixTranscodingUsage
      • DescribeRelayUsage
      • DescribeTrtcRoomUsage
    • Data Types
    • Error Codes
    • Appendix
      • Event ID Mapping Table

Common Params

Common parameters are used for all APIs authenticating requestors. Common parameters must be included in all API requests, and they will not be described in individual API documents.

The exact contents of the common parameters will vary depending on the version of the signature method you use.

Common parameters for Signature Algorithm v3

When the TC3-HMAC-SHA256 algorithm is used, the common parameters should be uniformly placed in the HTTP request header, as shown below:

Parameter NameTypeRequiredDescription
X-TC-ActionStringYesThe name of the API for the desired operation. For the specific value, see the description of common parameter Action in the input parameters in related API documentation. For example, the API for querying the CVM instance list is DescribeInstances.
X-TC-RegionStringYesRegion parameter, which is used to identify the region to which the data you want to work with belongs. For values supported for an API, see the description of common parameter Region in the input parameters in related API documentation. Note: This parameter is not required for some APIs (which will be indicated in related API documentation), and will not take effect even it is passed.
X-TC-TimestampIntegerYesThe current UNIX timestamp that records the time when the API request was initiated, for example, 1529223702. Note: If the difference between the UNIX timestamp and the server time is greater than 5 minutes, a signature expiration error may occur.
X-TC-VersionStringYesAPI version of the action. For the valid values, see the description of the common input parameter Version in the API documentation. For example, the version of CVM is 2017-03-12.
AuthorizationStringYesThe HTTP authentication request header, for example:
TC3-HMAC-SHA256 Credential=AKIDEXAMPLE/Date/service/tc3_request, SignedHeaders=content-type;host, Signature=fe5f80f77d5fa3beca038a248ff027d0445342fe2855ddc963176630326f1024
Here:
- TC3-HMAC-SHA256: Signature method, currently fixed as this value;
- Credential: Signature credential; AKIDEXAMPLE is the SecretId; Date is a date in UTC time, and this value must match the value of X-TC-Timestamp (a common parameter) in UTC time format; service is the name of the product/service, and is generally a domain name prefix. For example, a domain name cvm.tencentcloudapi.com refers to the CVM product and the value would be cvm;
- SignedHeaders: The headers that contains the authentication information; content-type and host are the required headers;
- Signature: Signature digest.
X-TC-TokenStringNoThe token used for a temporary certificate. It must be used with a temporary key. You can obtain the temporary key and token by calling a CAM API. No token is required for a long-term key.

Assuming you want to query the list of Cloud Virtual Machine instances in the Guangzhou region, the request structure in the form of request URL, request header and request body may be as follows:

Example of an HTTP GET request structure:

https://cvm.tencentcloudapi.com/?Limit=10&Offset=0

Authorization: TC3-HMAC-SHA256 Credential=AKIDz8krbsJ5yKBZQpn74WFkmLPx3EXAMPLE/2018-10-09/cvm/tc3_request, SignedHeaders=content-type;host, Signature=5da7a33f6993f0614b047e5df4582db9e9bf4672ba50567dba16c6ccf174c474
Content-Type: application/x-www-form-urlencoded
Host: cvm.tencentcloudapi.com
X-TC-Action: DescribeInstances
X-TC-Version: 2017-03-12
X-TC-Timestamp: 1539084154
X-TC-Region: ap-guangzhou

The following example shows you how to structure an HTTP POST (application/json) request:

https://cvm.tencentcloudapi.com/

Authorization: TC3-HMAC-SHA256 Credential=AKIDEXAMPLE/2018-05-30/cvm/tc3_request, SignedHeaders=content-type;host, Signature=582c400e06b5924a6f2b5d7d672d79c15b13162d9279b0855cfba6789a8edb4c
Content-Type: application/json
Host: cvm.tencentcloudapi.com
X-TC-Action: DescribeInstances
X-TC-Version: 2017-03-12
X-TC-Timestamp: 1527672334
X-TC-Region: ap-guangzhou

{"Offset":0,"Limit":10}

Example of an HTTP POST (multipart/form-data) request structure (only supported by specific APIs):

https://cvm.tencentcloudapi.com/

Authorization: TC3-HMAC-SHA256 Credential=AKIDEXAMPLE/2018-05-30/cvm/tc3_request, SignedHeaders=content-type;host, Signature=582c400e06b5924a6f2b5d7d672d79c15b13162d9279b0855cfba6789a8edb4c
Content-Type: multipart/form-data; boundary=58731222010402
Host: cvm.tencentcloudapi.com
X-TC-Action: DescribeInstances
X-TC-Version: 2017-03-12
X-TC-Timestamp: 1527672334
X-TC-Region: ap-guangzhou

--58731222010402
Content-Disposition: form-data; name="Offset"

0
--58731222010402
Content-Disposition: form-data; name="Limit"

10
--58731222010402--

Common parameters for Signature Algorithm v1

To adopt the HmacSHA1 and HmacSHA256 signature methods, common parameters must be put into the request string, as shown below:

Parameter NameTypeRequiredDescription
ActionStringYesThe name of the API for the desired operation. For the specific value, see the description of common parameter Action in the input parameters in related API documentation. For example, the API for querying the CVM instance list is DescribeInstances.
RegionStringYesRegion parameter, which is used to identify the region to which the data you want to work with belongs. For values supported for an API, see the description of common parameter Region in the input parameters in related API documentation. Note: This parameter is not required for some APIs (which will be indicated in related API documentation), and will not take effect even if it is passed.
TimestampIntegerYesThe current UNIX timestamp that records the time when the API request was initiated, for example, 1529223702. If the difference between the value and the current system time is too large, a signature expiration error may occur.
NonceIntegerYesA random positive integer used along with Timestamp to prevent replay attacks.
SecretIdStringYesThe identifying SecretId obtained on the Cloud API Key page. A SecretId corresponds to a unique SecretKey which is used to generate the request signature (Signature).
SignatureStringYesRequest signature used to verify the validity of this request. This is calculated based on the actual input parameters. For more information about how this is calculated, see the API authentication documentation.
VersionStringYesAPI version of the action. For the valid values, see the description of the common input parameter Version in the API documentation. For example, the version of CVM is 2017-03-12.
SignatureMethodStringNoSignature method. Currently, only HmacSHA256 and HmacSHA1 are supported. The HmacSHA256 algorithm is used to verify the signature only when this parameter is specified as HmacSHA256. In other cases, the signature is verified with HmacSHA1.
TokenStringNoThe token used for a temporary certificate. It must be used with a temporary key. You can obtain the temporary key and token by calling a CAM API. No token is required for a long-term key.

Assuming you want to query the list of Cloud Virtual Machine instances in the Guangzhou region, the request structure in the form of request URL, request header and request body may be as follows:

Example of an HTTP GET request structure:

https://cvm.tencentcloudapi.com/?Action=DescribeInstances&Version=2017-03-12&SignatureMethod=HmacSHA256&Timestamp=1527672334&Signature=37ac2f4fde00b0ac9bd9eadeb459b1bbee224158d66e7ae5fcadb70b2d181d02&Region=ap-guangzhou&Nonce=23823223&SecretId=AKIDEXAMPLE

Host: cvm.tencentcloudapi.com
Content-Type: application/x-www-form-urlencoded

Example of an HTTP POST request structure:

https://cvm.tencentcloudapi.com/

Host: cvm.tencentcloudapi.com
Content-Type: application/x-www-form-urlencoded

Action=DescribeInstances&Version=2017-03-12&SignatureMethod=HmacSHA256&Timestamp=1527672334&Signature=37ac2f4fde00b0ac9bd9eadeb459b1bbee224158d66e7ae5fcadb70b2d181d02&Region=ap-guangzhou&Nonce=23823223&SecretId=AKIDEXAMPLE

Region List

The supported Region field values for all APIs in this product are listed as below. For any API that does not support any of the following regions, this field will be described additionally in the relevant API document.

RegionValue
Southeast Asia (Bangkok)ap-bangkok
North China (Beijing)ap-beijing
South China (Guangzhou)ap-guangzhou
Hong Kong/Macao/Taiwan (China) (Hong Kong (China))ap-hongkong
Southeast Asia (Jakarta)ap-jakarta
South Asia (Mumbai)ap-mumbai
East China (Shanghai)ap-shanghai
Southeast Asia (Singapore)ap-singapore
North America (Toronto)na-toronto