This topic describes the request syntax and signature method V3. This version uses common request headers to pass the required parameters of API operations, which shields the differences between different API styles. This allows you to use the same signature method for different API styles and call Alibaba Cloud API operations in a more standard and easier way. This topic helps you understand and use the request syntax and signature method V3 of Alibaba Cloud SDKs. This topic also describes how to construct a canonicalized HTTP request and how to use a correct signature algorithm to verify the identity of a request sender. This ensures the integrity and security of the transmitted data. You can read this topic to develop Alibaba Cloud OpenAPI SDKs.
HTTP request syntax
The following table describes the components of an Alibaba Cloud API request.
Component | Required | Description | Example |
Protocol | Yes | The protocol that is used to send the API request. You can read the API references of each Alibaba Cloud service to understand the protocol that is used. You can send a request over | https:// |
Endpoint | Yes | The endpoint of the Alibaba Cloud service API. Topics that list the endpoints of each Alibaba Cloud service are available. You can view the endpoints of a service in different regions in these topics. | cs.aliyuncs.com |
resource_URI_parameters | Yes | The identifier of the resource that you want to access. | /clusters/{cluster_id}/triggers |
RequestHeader | Yes | The request headers. In most cases, information such as the API version number, hostname, and authentication information is included. For more information, see the "Request headers" section of this topic. | x-acs-action |
RequestBody | Yes | The operation-specific parameters in the request body. For more information, visit OpenAPI Portal. | cluster_id |
HTTPMethod | Yes | The HTTP method that is used to send the request. Valid values: PUT, POST, GET, and DELETE. | POST |
Request headers
The following table describes the request headers of an Alibaba Cloud API request.
Header | Type | Required | Description | Example |
x-acs-action | String | Yes | The operation that you want to perform. You can search for the API operation that you want to call in OpenAPI Portal. | CreateTrigger |
x-acs-version | String | Yes | The version number of the API. You can view the API version of the service that you want to access in OpenAPI Portal. | 2015-12-15 |
Authorization | String | Yes if the request is non-anonymous | The authentication information used to verify the validity of the request. Format: Authorization: SignatureAlgorithm Credential=AccessKeyId,SignedHeaders=SignedHeaders,Signature=Signature. SignatureAlgorithm: the encryption method of the signature string. Set the value to ACS3-HMAC-SHA256. Credential: the AccessKey ID that is provided by Alibaba Cloud. You can view your AccessKey ID in the Resource Access Management (RAM) console. For more information about how to create an AccessKey pair, see Obtain an AccessKey pair. SignedHeaders: the names of the request headers that are used for signature calculation. Note: All common request headers except the Authorization header must be used for signature calculation. Signature: the signature string of the request. For more information, see the "Signature method" section of this topic. | ACS3-HMAC-SHA256 Credential=YourAccessKeyId,SignedHeaders=content-type;host;x-acs-timestamp,Signature=6b595d672d79c15b18edb4ccfba6789a24a6f2b82c400e03162d9279b08555d7 |
x-acs-signature-nonce | String | No | A unique, random number used to prevent replay attacks. We recommend that you use different numbers for different requests. | 15215528852396 |
x-acs-date | String | Yes | The timestamp of the request. Specify the time in the ISO 8601 standard in the yyyy-MM-ddTHH:mm:ssZ format. The timestamp must be in UTC. Example: 2018-01-01T12:00:00Z. The timestamp must be within 15 minutes before the request is sent. | 2018-01-01T12:00:00Z |
host | String | Yes | The endpoint of the Alibaba Cloud service API. For more information, see the HTTP request syntax section of this topic. | cs.aliyuncs.com |
x-acs-content-sha256 | String | Yes | The hash value of the request body. The hash value is encoded in Base16. The value of this header is the same as that of the HashedRequestPayload parameter. | |
x-acs-security-token | String | Yes if Security Token Service (STS) is used for authentication | The STS token. Set this header to the value of the SecurityToken parameter in the response of the Assumerole operation. |
API request construction
A complete API request consists of the following parts:
HTTPMethod /resource_URI_parameters
RequestHeader
RequestBody
Request parameters consist of common request headers and operation-specific parameters. The common request headers contain information such as the API version number and authentication information.
HTTPMethod: the HTTP method that is used to send the request. Valid values: PUT, POST, GET, and DELETE. For more information, see the HTTP request syntax section of this topic.
resource_URI_parameters: the identifier of the resource that you want to access. Example:
/cluster
. For more information, see the HTTP request syntax section of this topic.RequestHeader: the request headers. In most cases, information such as the API version number, endpoint, and authentication information is included. For more information, see the HTTP request syntax section of this topic.
RequestBody: the operation-specific parameters in the request body. For more information, see the HTTP request syntax section of this topic.
Sample request to call the RunInstances operation:
POST /?ImageId=win2019_1809_x64_dtc_zh-cn_40G_alibase_20230811.vhd&RegionId=cn-shanghai HTTP/1.1
Authorization: ACS3-HMAC-SHA256 Credential=YourAccessKeyId,SignedHeaders=host;x-acs-action;x-acs-content-sha256;x-acs-date;x-acs-signature-nonce;x-acs-version,Signature=e521358f7776c97df52e6b2891a8bc73026794a071b50c3323388c4e0df64804
x-acs-action: RunInstances
host: ecs.cn-shanghai.aliyuncs.com
x-acs-date: 2023-10-26T09:01:01Z
x-acs-version: 2014-05-26
x-acs-content-sha256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
x-acs-signature-nonce: d410180a5abf7fe235dd9b74aca91fc0
user-agent: AlibabaCloud (Mac OS X; x86_64) Java/1.8.0_352-b08 tea-util/0.2.6 TeaDSL/1
accept: application/json
Encoding
Requests and responses are encoded in UTF-8.
Responses
Each response returns a unique request ID regardless of whether the request is successful. All responses are returned in a unified format. If an API call is successful, a request ID is returned. The HTTP status code is 2xx, which is not displayed in the response. Sample success response:
{
"RequestId": "4C467B38-3910-447D-87BC-AC049166F216" /* Return Result Data */
}
If an API call fails, a request ID, a service node, an error code, and an error message are returned. The HTTP status code is 4xx or 5xx. Sample failure response:
{
"code": "400", /* Error Code */
"message": "Cluster permission denied", /* Error Message */
"requestId": "A026BC61-0523-5A6D-A5F3-314A3D92FD50", /* Request ID */
"status": 400 /* HTTP Status Code */
}
If an API call fails, you can troubleshoot the error on the OpenAPI problem diagnosis page in OpenAPI Portal based on the request ID that is returned. For more information about error codes, visit the Global error code and Error Codes pages. If the error persists, you can submit a ticket and provide the endpoint and request ID. For more information about the endpoint, see the HTTP request syntax section of this topic.
Signature method
You must sign all API requests to ensure security. Alibaba Cloud uses the request signature to verify the identity of the API caller. Each API request must contain a signature, regardless of whether the request is sent over HTTP or HTTPS. This section describes how to sign API requests.
For each HTTP or HTTPS request, Alibaba Cloud uses the request signature to verify the identity of the API caller. You can perform the following steps to sign a request:
Step 1: Construct a canonicalized request
To use an AccessKey pair to calculate or verify a signature, you must construct a canonicalized request. The client and API gateway must use the same request specifications so that they can obtain the same signature string for an HTTP request to complete identity verification.
Construct a canonicalized request based on the following pseudocode:
CanonicalRequest =
HTTPRequestMethod + '\n' + // The HTTP method in uppercase letters.
CanonicalURI + '\n' + // The canonicalized URI.
CanonicalQueryString + '\n' + // The canonicalized query string.
CanonicalHeaders + '\n' + // The canonicalized request headers.
SignedHeaders + '\n' + // The request headers that are used for signature calculation.
HashedRequestPayload
HTTPRequestMethod: the HTTP method in uppercase letters, such as POST and GET.
CanonicalURI
The encoded resource path in the URL. The resource path is the part between the endpoint and the query string. The path includes the forward slash (
/
) following the endpoint but excludes the question mark (?
) preceding the query string. You must use a canonicalized URI for signature calculation. To construct a canonicalized URI, encode the strings separated by forward slashes (/
) in UTF-8 based on RFC 3986. Encoding rules:Letters, digits, hyphens (
-
), underscores (_
), periods (.
), and tildes (~
) do not need to be encoded.Other characters must be percent encoded in the
%XY
format.XY
indicates the ASCII code of the characters in hexadecimal notation. For example, double quotation marks ("
) are encoded as%22
.Extended UTF-8 characters are encoded in the
%XY%ZA…
format.Spaces must be encoded as
%20
instead of (+
). The preceding encoding scheme is similar to but slightly different from theapplication/x-www-form-urlencoded
Multipurpose Internet Mail Extension (MIME) encoding algorithm.If you use
java.net.URLEncoder
in the Java standard library, usepercentEncode
to encode the strings. In the encoded strings, replace the plus sign (+
) with%20
, the asterisk (*
) with%2A
, and%7E
with a tilde (~
). This way, you can obtain encoded strings that match the preceding encoding scheme.
Note: If the resource path is empty, use a forward slash (
/
) as the value of the CanonicalURI parameter.CanonicalQueryString: the canonicalized query string. You can perform the following steps to construct the canonicalized query string:
Sort the parameters in the query string by the parameter name in alphabetical order. For parameters with the same name, sort the parameters by the parameter value in alphabetical order.
Encode the parameter names and values in UTF-8 based on RFC 3986. The encoding rules are the same as those used to construct the canonicalized URI.
Use an equal sign (
=
) to concatenate the encoded name and value of each parameter. For a parameter without a value, use an empty string as the parameter value.Sort the parameters by the encoded parameter name in alphabetical order. For parameters with the same name, sort the parameters by the encoded parameter value in alphabetical order.
Use ampersands (
&
) to concatenate the encoded parameters in the order obtained in the previous step.
Note: If the query string is empty, use an empty string as the canonicalized query string, which is a blank line.
CanonicalizedHeaders: the non-standard HTTP headers. Non-standard HTTP headers are headers whose names are prefixed with
x-acs-
in the request. You can perform the following steps to construct canonicalized headers:Convert the names of all headers that are used for signature calculation to lowercase letters.
Remove the spaces before and after the value of a header. If a header has multiple values, remove the spaces before and after each value, sort the values in alphabetical order, and then use commas (
,
) to concatenate the values.Use a colon (
:
) to concatenate the name and value of a header obtained in the preceding steps and add a line break at the end to construct a canonicalized header.Concatenate all canonicalized headers by the lowercase header name in alphabetical order.
If no headers are used for signature calculation, use an empty string as the canonicalized headers.
Note: All common request headers except the Authorization header must be used for signature calculation.
SignedHeaders: the names of the headers that are used for signature calculation. This parameter contains the same headers as those in the CanonicalHeaders parameter. You can perform the following steps to construct signed headers:
Convert the names of headers in the CanonicalHeaders parameter to lowercase letters.
Use semicolons (
;
) to concatenate all the headers by lowercase header name in alphabetical order. Example:content-type;host;x-acs-date
.Pseudocode:
CanonicalHeaderEntry = Lowercase(HeaderName) + ':' + Trim(HeaderValue) + '\n' CanonicalHeaders = CanonicalHeaderEntry0 + CanonicalHeaderEntry1 + ... + CanonicalHeaderEntryN
HashedRequestPayload: the hash value of the request body. The following pseudocode shows how to generate the hash value:
HashedRequestPayload = HexEncode(Hash(RequestPayload))
. RequestPayload indicates the request body.Hash() indicates the hash algorithm. Only the SHA256 algorithm is supported. For example, if the encryption method of the signature string is ACS3-HMAC-SHA256, you must use SHA256 as the hash algorithm.
HexEncode() encodes the hash value in Base16. This function returns an encoded hash value in the hexadecimal format in lowercase letters.
Note: If the request body is empty, such as in a GET request, use an empty string as the value of the RequestPayload parameter.
Table 1: Mappings among encryption methods of the signature string, signature calculation algorithms, and hash algorithms
Encryption method of signature string (SignatureAlgorithm)
Hash algorithm used to process RequestPayload and CanonicalRequest (Hash)
Algorithm for signature calculation
(SignatureMethod)
ACS3-HMAC-SHA256
SHA256
HMAC-SHA256
Step 2: Construct a string-to-sign
Construct a string-to-sign based on the following pseudocode:
StringToSign =
SignatureAlgorithm + '\n' +
HashedCanonicalRequest
SignatureAlgorithm
The encryption method of the signature string. Only ACS3-HMAC-SHA256 is supported. The MD5- or SHA1-based algorithms are no longer supported.
HashedCanonicalRequest
The hash value of the canonicalized request. The following pseudocode shows how to generate the hash value:
HashedCanonicalRequest = HexEncode(Hash(CanonicalRequest))
Calculate the hash value of the canonicalized request obtained in Step 1. Select a hash algorithm based on the encryption method of the signature string, which is specified by the SignatureAlgorithm parameter. For more information, see the "Table 1" section of this topic. Only ACS3-HMAC-SHA256 is supported as the encryption method. In this case, you must use SHA256 as the hash algorithm.
Encode the hash value obtained in the previous step in Base16.
Step 3: Calculate the signature string
Calculate the signature string based on the following pseudocode:
Signature = HexEncode(SignatureMethod(Secret, StringToSign))
StringToSign: the string-to-sign that is constructed in Step 2. The value is encoded in UTF-8.
SignatureMethod: the algorithm for signature calculation. Select an algorithm based on the encryption method of the signature string, which is specified by the SignatureAlgorithm parameter. For more information, see the "Table 1" section of this topic.
Secret: the AccessKey secret provided by Alibaba Cloud. The value is in the binary format.
HexEncode: the function that is used to encode values in Base16.
Step 4: Add the signature string to the request
After you obtain the signature string, specify the Authorization header in the request in the following format: Authorization:<SignatureAlgorithm> Credential=<AccessKeyId>,SignedHeaders=<SignedHeaders>,Signature=<Signature>
. Example:
Authorization:ACS3-HMAC-SHA256 Credential=YourAccessKeyId,SignedHeaders=content-type;host;x-acs-timestamp,Signature=6b595d672d79c15b18edb4ccfba6789a24a6f2b82c400e03162d9279b08555d7
Signature example
In this example, the RunInstances operation of Elastic Compute Service (ECS) is called. Your AccessKey ID is YourAccessKeyId.
Your AccessKey secret is YourAccessKeySecret. The value of the x-acs-signature-nonce is 3156853299f313e23d1673dc12e1703d, and the timestamp of the request is 2023-10-26T10:22:32Z. You can perform the following steps to sign the request:
Construct a canonicalized request.
POST
/
ImageId=win2019_1809_x64_dtc_zh-cn_40G_alibase_20230811.vhd&RegionId=cn-shanghai
host:ecs.cn-shanghai.aliyuncs.com
x-acs-action:RunInstances
x-acs-content-sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
x-acs-date:2023-10-26T10:22:32Z
x-acs-signature-nonce:3156853299f313e23d1673dc12e1703d
x-acs-version:2014-05-26
host;x-acs-action;x-acs-content-sha256;x-acs-date;x-acs-signature-nonce;x-acs-version
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
Construct a string-to-sign.
ACS3-HMAC-SHA256
7ea06492da5221eba5297e897ce16e55f964061054b7695beedaac1145b1e259
Calculate the signature string.
06563a9e1b43f5dfe96b81484da74bceab24a1d853912eee15083a6f0f3283c0
Add the signature string to the request.
POST /?ImageId=win2019_1809_x64_dtc_zh-cn_40G_alibase_20230811.vhd&RegionId=cn-shanghai HTTP/1.1
Authorization: ACS3-HMAC-SHA256 Credential=YourAccessKeyId,SignedHeaders=host;x-acs-action;x-acs-content-sha256;x-acs-date;x-acs-signature-nonce;x-acs-version,Signature=e521358f7776c97df52e6b2891a8bc73026794a071b50c3323388c4e0df64804
x-acs-action: RunInstances
host: ecs.cn-shanghai.aliyuncs.com
x-acs-date: 2023-10-26T09:01:01Z
x-acs-version: 2014-05-26
x-acs-content-sha256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
x-acs-signature-nonce: d410180a5abf7fe235dd9b74aca91fc0
user-agent: AlibabaCloud (Mac OS X; x86_64) Java/1.8.0_352-b08 tea-util/0.2.6 TeaDSL/1
accept: application/json