Sign Requests

When you call an API operation, the API gateway requires the application to provide a signature to verify your identity. This topic describes how to generate a signature in a call.

Signature algorithm

The API gateway uses the Hash-based Message Authentication Code (HMAC) SHA-256 algorithm to create digests. Using the Postman software, you can verify the encryption result of sign in the API request. For more information about the verification method, see Verify the signature result.

Token management API

• Scope of application: operations that are used to get or refresh tokens.

• Signature algorithm:

  sign = HMAC-SHA256(client_id + t + nonce + stringToSign, secret).toUpperCase()
  

• Procedure to sign a request:

  1. nonce: the universally unique identifier (UUID) generated for each API request. Combined with the timestamp, the UUID ensures the uniqueness of API requests. The nonce field is optional. stringToSign is the signature string.
  2. Concatenate the value of client_id, the 13-digit standard timestamp (t), nonce, and stringToSign of the specified request to create a string.
  3. Create a hash digest value based on the string and the value of secret, and encode the hash digest value into a new string.
  4. Capitalize all letters of the new string.

Service management API

• Scope of application: operations that are used to manage services rather than tokens.

• Signature algorithm:

  str = client_id + access_token + t + nonce + stringToSign
  sign = HMAC-SHA256(str, secret).toUpperCase()
  

• Procedure to sign a request:

  1. nonce: the universally unique identifier (UUID) generated for each API request. Combined with the timestamp, the UUID ensures the uniqueness of API requests. The nonce field is optional. stringToSign is the signature string.
  2. Concatenate the value of client_id, access_token, the 13-digit standard timestamp (t), nonce, and stringToSign of the specified request to create a string.
  3. Create a hash digest value based on the string and the value of secret, and encode the hash digest value into a new string.
  4. Capitalize all letters of the new string.

stringToSign signature string

• Components:

  String stringToSign=
  HTTPMethod + "\n" +
  Content-SHA256 + "\n" +
  Headers + "\n" +
  Url
  

• Signature string fields:

  1. HTTPMethod: All letters of each method name are capitalized. Example: POST and PUT.

  2. Content-SHA256 represents the SHA-256 value of a request body. SHA-256 is calculated only when the body is not a form. Calculation:

     String content-SHA256 = SHA256(bodyStream.getbytes("UTF-8")); //bodyStream is a byte array
     

     An empty body is still encrypted into e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855.

  3. Headers refers to the concatenated string of the Key and Value of the Header involved in the signature calculation.

     The fields of the headers in the signature are concatenated with colons (:) as the value of Signature-Headers. The Header is in the following format:

     client_id:xxx
     Signature-Headers : Key1:Key2
     Key1:xxx
     Key2:xxx
     key3:xxx (not included in the signature calculation)
     nonce:xxx
     ·····
     

     Headers calculation (only the keys in Signature-Headers are calculated):

     String Headers =
     HeaderKey1 + ":" + HeaderValue1 + "\n" +
     HeaderKey2 + ":" + HeaderValue2 + "\n" +
     ...
     HeaderKeyN + ":" + HeaderValueN + "\n"
     

  4. URL: the Form parameter in Path, Query, and Body.

     Sort the keys in alphabetical order, and follow the method below to concatenate Query and Form. If the Query or Form parameters are empty, the URL is the set value of Path and a connector ? is not required.

     String url =
     Path +
     "?" +
     Key1 + "=" + Value1 +
     "&" + Key2 + "=" + Value2 +
     "&" + Key3 +
     ...
     "&" + KeyN + "=" + ValueN
     

Signature examples

Sample parameters

The operation to get the user list is used as an example. The schema parameter is apps. No body parameter is required.

Signature algorithm for token management operations

1. Concatenate a stringToSign signature string.

   stringToSign=GET
   e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
   area_id:29a33e8796834b1efa6
   call_id:8afdb70ab2ed11eb85290242ac130003
   
   /v1.0/token?grant_type=1
   

2. Create a string to be signed.

   1KAD46OrT9HafiKdsXeg15889257780005138cc3a9033d69856923fd07b491173GET
   e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
   area_id:29a33e8796834b1efa6
   call_id:8afdb70ab2ed11eb85290242ac130003
   
   /v1.0/token?grant_type=1
   

3. Create a hash digest value based on the string and the value of the secret, and encode the hash digest value into a new string.

   • Hash digest value:

     HMAC-SHA256(1KAD46OrT9HafiKdsXeg15889257780005138cc3a9033d69856923fd07b491173GET
     e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
     area_id:29a33e8796834b1efa6
     call_id:8afdb70ab2ed11eb85290242ac130003
     
     /v1.0/token?grant_type=1,4OHBOnWOqaEC1mWXOpVL3yV50s0qGSRC)
     

   • New string:

     9e48a3e93b302eeecc803c7241985d0a34eb944f40fb573c7b5c2a82158af13e
     

4. Capitalize all letters of the new string.

   9E48A3E93B302EEECC803C7241985D0A34EB944F40FB573C7B5C2A82158AF13E
   

Signature algorithm for service management operations

1. Concatenate a stringToSign signature string.

   stringToSign=GET
   e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
   area_id:29a33e8796834b1efa6
   call_id:8afdb70ab2ed11eb85290242ac130003
   
   /v2.0/apps/schema/users?page_no=1&page_size=50
   

2. Create a string to be signed.

   1KAD46OrT9HafiKdsXeg3f4eda2bdec17232f67c0b188af3eec115889257780005138cc3a9033d69856923fd07b491173GET
   e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
   area_id:29a33e8796834b1efa6
   call_id:8afdb70ab2ed11eb85290242ac130003
   
   /v2.0/apps/schema/users?page_no=1&page_size=50
   

3. Create a hash digest value based on the string and the value of secret, and encode the hash digest value into a new string.

   • Hash digest value:

     HMAC-SHA256(1KAD46OrT9HafiKdsXeg3f4eda2bdec17232f67c0b188af3eec115889257780005138cc3a9033d69856923fd07b491173GET
     e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
     area_id:29a33e8796834b1efa6
     call_id:8afdb70ab2ed11eb85290242ac130003
     
     /v2.0/apps/schema/users?page_no=1&page_size=50,4OHBOnWOqaEC1mWXOpVL3yV50s0qGSRC)
     

   • New string:

     ae4481c692aa80b25f3a7e12c3a5fd9bbf6251539dd78e565a1a72a508a88784
     

4. Capitalize all letters of the new string.

   AE4481C692AA80B25F3A7E12C3A5FD9BBF6251539DD78E565A1A72A508A88784
   

Implement the HMAC-SHA256 authentication scheme

Sample code for Java

Download the Sample code for Java.

Sample code for Go

Download the Sample code for Go.

Sample code for Node.js

Download the Sample code for Node.js.

Sample code for JavaScript

/**
Run the code online with this jsfiddle. Dependent upon an open source js library calledhttp://code.google.com/p/crypto-js/.
**/

<script src="https://cdnjs.cloudflare.com/ajax/libs/crypto-js/4.0.0/enc-base64.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/crypto-js/4.0.0/hmac-sha256.min.js"></script>

<script>
  var hash = CryptoJS.HmacSHA256("Message", "secret");
  var hashInBase64 = hash.toString().toUpperCase();
  document.write(hashInBase64);
</script>

Sample code for PHP

/**
PHP has built in methods for hash_hmac (PHP 5) and base64_encode (PHP 4, PHP 5) resulting in no outside dependencies. Say what you want about PHP but they have the cleanest code for this example.
**/

$s = strtoupper(hash_hmac("sha256", "Message", 'secret'));
echo var_dump($s);

Sample code for C#

using System;
using System.Security.Cryptography;

namespace Test
{
  public class MyHmac
  {
    public static string Encrypt(string message, string secret)
            {
                secret = secret ?? "";
                var encoding = new System.Text.UTF8Encoding();
                byte[] keyByte = encoding.GetBytes(secret);
                byte[] messageBytes = encoding.GetBytes(message);
                using (var hmacsha256 = new HMACSHA256(keyByte))
                {
                    byte[] hashmessage = hmacsha256.ComputeHash(messageBytes);
                    StringBuilder builder = new StringBuilder();
                    for (int i = 0; i < hashmessage.Length; i++)
                    {
                        builder.Append(hashmessage[i].ToString("x2"));
                    }
                    return builder.ToString().ToUpper();
                }
            }
  }
}

FAQs

How do I verify the encrypted signature?

During local development, you can test API requests with Postman to verify the encrypted signature. For more information, see Verify the signature result.