All Products
Document Center

Request signature description

Last Updated: Dec 01, 2017

Domain name

  • Each API belongs to an API group, and each API group has a unique domain name. These independent domain names are bound by the service provider. API Gateway uses a domain name to locate an API group.
  • The domain name is in the format of www.[Independent domain name].com/[Path]?[HTTPMethod]. At the public beta stage, the API user needs to obtain this domain name offline from the API service provider.
  • Alibaba Cloud API Gateway uses the domain name to locate a unique API group, and then locate the unique API through Path+HTTPMethod.
  • You must obtain API documentation in the deprecation environment from the API service provider. This documentation must include necessary parameter information, such as the domain name and path.

System headers

  • [Required] X-Ca-Key: AppKey
  • [Required] X-Ca-Signature: Signature string
  • [Optional] X-Ca-Timestamp: The time stamp in milliseconds passed by the API caller, that is, the milliseconds of the time from January 1, 1970 until now. By default, it is valid within 15 minutes.
  • [Optional] X-Ca-Nonce: The UUID generated by the API caller. This header is used with the time stamp to prevent replay.
  • [Optional] Content-MD5: When the request body is not a Form, calculate the MD5 value of the body and send that value to the cloud gateway for checking.
  • [Optional] X-Ca-Stage: The stage where the requested API belongs. Only test and release are supported, and the default value is release.

Signature verification

For more information about the demo (Java) of signature calculation, see here.

The signature calculation procedure is as follows:

Organize the strings involved in signature calculation

  1. String stringToSign=
  2. HTTPMethod + "\n" +
  3. Accept + "\n" +
  4. Content-MD5 + "\n"
  5. Content-Type + "\n" +
  6. Date + "\n" +
  7. Headers +
  8. Url

Each letter of the HTTPMethod value must be capitalized.

If Accept, Content-MD5, Content-Type, and Date are empty, add a linefeed (\n). If Headers is empty, a linefeed (\n) is not required. The specified Headers includes a linefeed (\n). For more information, see the headers organization method described as follows.


Content-MD5 indicates the MD5 value of the body. MD5 is only calculated when the body is not a Form. The calculation method is as follows:

  1. String content-MD5 = Base64.encodeBase64(MD5(bodyStream.getbytes("UTF-8")));

The bodyStream indicates the byte array.


Headers indicates the keys and values of the headers involved in signature calculation. Note that X-Ca-Signature and X-Ca-Signature-Headers are excluded in Headers signature calculation.

Headers organization method:

Rank the keys of all Headers involved in signature calculation in lexicographic order and then splice them in the following method:

  1. String headers =
  2. HeaderKey1 + ":" + HeaderValue1 + "\n"\+
  3. HeaderKey2 + ":" + HeaderValue2 + "\n"\+
  4. ...
  5. HeaderKeyN + ":" + HeaderValueN + "\n"

URL indicates the Form parameter in the Path+Query+Body. The organization method is as follows:

Rank the keys of Query+Form in lexicographic order and then splice them in the following method. If Query or Form is empty, the URL is equal to Path, and a question mark (?) is not required to be added.

  1. String url =
  2. Path +
  3. "?" +
  4. Key1 + "=" + Value1 +
  5. "&" + Key2 + "=" + Value2 +
  6. ...
  7. "&" + KeyN + "=" + ValueN

Note that Query or Form may have multiple values. If multiple values exist, use the first value for signature calculation.

Calculate the signature

  1. Mac hmacSha256 = Mac.getInstance("HmacSHA256");
  2. byte[] keyBytes = secret.getBytes("UTF-8");
  3. hmacSha256.init(new SecretKeySpec(keyBytes, 0, keyBytes.length, "HmacSHA256"));
  4. String sign = new String(Base64.encodeBase64(hmacSha256.doFinal(stringToSign.getBytes("UTF-8")),"UTF-8"));

The secret indicates the key corresponding to an app.

Pass the signature

Put the calculated signature in the Header of the Request. The key is X-Ca-Signature.

Separate the keys of all Headers involved in signature calculation by commas and put them in the Header of the Request regardless of the order. The key is X-Ca-Signature-Headers.

For more information about the demo of signature calculation, click here.