edit-icon download-icon

Sign REST APIs

Last Updated: Mar 12, 2018

To ensure the security of your API security, you must sign the API request. Alibaba Cloud uses the signature in the request to verify the identity of the person who calls the API.

Alibaba Cloud provides multiple SDKs and third-party SDKs to make the manual signature process more efficient. Click here to know more about Alibaba Cloud SDKs.

Signature overview

For REST APIs, you must add an Authorization header to the API request header according to the following format:

Authorization:acs:AccessKeyId:Signature

where:

  • acs: The abbreviation for Alibaba Cloud Service, a fixed value that cannot be changed.

  • AccessKeyId: The AccessKey ID used to call the API.

  • Signature: The signature generated by performing symmetric encryption on the request by using the AccessKey Secret.

Calculate signatures

According to RFC 2104, calculate the HMAC value of the encoded and formatted string. The calculated HMAC value is the signature.

  1. Signature = Base64( HMAC-SHA1( AccessSecret, UTF-8-Encoding-Of(
  2. StringToSign) ) )

The signature algorithm follows the RFC 2014 HMAC-SHA1 specification. Different APIs contain different request parameters, which result in different HMAC signatures.

1. Construct the string to sign

The string to sign is composed of the following components:

Construct the string to sign in the required order as follows:

  1. StringToSign =
  2. //HTTP header
  3. HTTP-Verb + "\n" +
  4. Accept + "\n" +
  5. Content-MD5 + "\n" +//The MD5 value of the body is put here
  6. Content-Type + "\n" +
  7. Date + "\n" +
  8. //Alibaba Cloud header
  9. CanonicalizedHeaders +
  10. //Canonicalized resource
  11. CanonicalizedResource

Example: original request

  1. POST /stacks?name=test_alert&status=COMPLETE HTTP/1.1
  2. Host: ***.aliyuncs.com
  3. Accept: application/json
  4. Content-MD5: ChDfdfwC+Tn874znq7Dw7Q==
  5. Content-Type: application/x-www-form-urlencoded;charset=utf-8
  6. Date: Thu, 22 Feb 2018 07:46:12 GMT
  7. x-acs-signature-nonce: 550e8400-e29b-41d4-a716-446655440000
  8. x-acs-signature-method: HMAC-SHA1
  9. x-acs-signature-version: 1.0
  10. x-acs-version: 2016-01-02

Example: constructed string to sign

  1. POST
  2. application/json
  3. ChDfdfwC+Tn874znq7Dw7Q==
  4. application/x-www-form-urlencoded;charset=utf-8
  5. Thu, 22 Feb 2018 07:46:12 GMT
  6. x-acs-signature-nonce: 550e8400-e29b-41d4-a716-446655440000
  7. x-acs-signature-method:HMAC-SHA1
  8. x-acs-signature-version:1.0
  9. x-acs-version:2016-01-02
  10. /stacks?name=test_alert&status=COMPLETE

HTTP header

The values of the Accept, Content-MD5, Content-Type, and Date parameters must be included when calculating the signature, but the AccessKey is not included. Sort the parameter values in the lexicographical order. Use \n to fill up the empty values.

ParameterDescription
Accept

The type of the response to return. Valid values:

application/json | application/xml

Content-MD5 The base-64 encoded 128-bit MD5 digest.
Content-Type The content type of the request defined in RFC 2616.
Date

The time at which the request is created in the GMT format.

Example: Wed, 05 Sep. 2012 23:00:00 GMT

Example: original header

  1. Accept: application/json
  2. Content-MD5: ChDfdfwC+Tn874znq7Dw7Q==
  3. Content-Type: application/x-www-form-urlencoded;charset=utf-8
  4. Date: Thu, 22 Feb 2018 07:46:12 GMT

Example: canonical header

  1. application/json
  2. ChDfdfwC+Tn874znq7Dw7Q==
  3. application/x-www-form-urlencoded;charset=utf-8
  4. Thu, 22 Feb 2018 07:46:12 GMT

Alibaba Cloud header

The Alibaba Cloud header, not a standard header, are the parameters with the x-acs- prefix in the request. It includes the following:

ParameterDescription
x-acs-signature-nonce A random number of the signature to prevent from network attacks. You must use different random numbers for different requests.
x-acs-signature-method

The hash method used to calculate the signature. Valid value:

HMAC-SHA1

x-acs-signature-version

The version of the signature. Valid value:

1.0

x-acs-version The version of the API to use. Go to the API documentation of the specific product to get the API version.

Follow these steps to construct the Alibaba Cloud header:

  1. Change all the parameters starting with x-acs- to lowercase. For example, change X-acs-OSS-Meta-Name: TaoBao to x-acs-oss-meta-name: TaoBao.

  2. Sort the Alibaba Cloud header in the ascending lexicographical order.

  3. Delete any space in the delimiter between the header and the content. For example, change x-acs-oss-meta-name: TaoBao,Alipay to x-acs-oss-meta-name:TaoBao,Alipay.

  4. Use \n to separate the headers and the contents.

Example: original Alibaba Cloud header

  1. x-acs-signature-nonce: 550e8400-e29b-41d4-a716-446655440000
  2. x-acs-signature-method: HMAC-SHA1
  3. x-acs-signature-version: 1.0
  4. x-acs-version: 2016-01-02

Example: canonical Alibaba Cloud header

  1. x-acs-signature-nonce:550e8400-e29b-41d4-a716-446655440000
  2. x-acs-signature-method:HMAC-SHA1
  3. x-acs-signature-version:1.0
  4. x-acs-version:2016-01-02

Canonical resource

CanonicalizedResource is the canonical description for the resource to access. Sort the sub resources together with the query parameters (all the parameters after the question mark) in the descending lexicographical order and use the ampersand (&) to separate parameters.

Example: original request

  1. /stacks?status=COMPLETE&name=test_alert

Example: canonical request

  1. /stacks?name=test_alert&status=COMPLETE

Body

Use MD5 to encrypt the body, and then use base-64 to encode it. Add the final content to Content-MD5.

2. Add the signature to the request

Add the calculated signature to the request header as follows:

  1. Authorization: acs AccessKeyId:Signature
Thank you! We've received your feedback.