Sign Requests

Last Updated on: 2024-09-10 07:19:13

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.

Note

To improve service security, the API gateway has updated the signature algorithm. New projects created after June 30, 2021 can be verified only with the new algorithm. Projects created earlier than June 30, 2021 still support the old algorithm. However, to ensure data security, we recommend that you update to the new signature algorithm.

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
```
  Note
  
  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

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

Important

For more information about the request headers, see Request Structure.

Parameter	Value
URL	/v2.0/apps/schema/users
method	GET
client_id	1KAD46OrT9HafiKdsXeg
secret	4OHBOnWOqaEC1mWXOpVL3yV50s0qGSRC
t	1588925778000
access_token	3f4eda2bdec17232f67c0b188af3eec1
sign_method	HMAC-SHA256 Note: In the signature digest algorithm, the request header is required.
nonce	5138cc3a9033d69856923fd07b491173
Signature-Headers	area_id:call_id
area_id (Customized)	29a33e8796834b1efa6
call_id (Customized)	8afdb70ab2ed11eb85290242ac130003
page_no	1
page_size	50

Signature algorithm for token management operations

Concatenate a stringToSign signature string.

stringToSign=GET
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
area_id:29a33e8796834b1efa6
call_id:8afdb70ab2ed11eb85290242ac130003

/v1.0/token?grant_type=1

Create a string to be signed.

1KAD46OrT9HafiKdsXeg15889257780005138cc3a9033d69856923fd07b491173GET
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
area_id:29a33e8796834b1efa6
call_id:8afdb70ab2ed11eb85290242ac130003

/v1.0/token?grant_type=1

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

Capitalize all letters of the new string.

9E48A3E93B302EEECC803C7241985D0A34EB944F40FB573C7B5C2A82158AF13E

Signature algorithm for service management operations

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

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

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

Capitalize all letters of the new string.

AE4481C692AA80B25F3A7E12C3A5FD9BBF6251539DD78E565A1A72A508A88784

Implement the HMAC-SHA256 authentication scheme

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.

Private Cloud

Sign Requests

Signature algorithm

Note

Token management API

Service management API

stringToSign signature string

Note

Signature examples

Signature examples

Important

Signature algorithm for token management operations

Signature algorithm for service management operations

Implement the HMAC-SHA256 authentication scheme

Sample code for Java

Sample code for Go

Sample code for Node.js

Sample code for JavaScript

Sample code for PHP

Sample code for C#

FAQs

How do I verify the encrypted signature?

This page contains content