Skip to content

Signature Calculation

This document describes the HMAC-SHA256 signature calculation process used for API authentication. The signature is generated by combining the request URL, query parameters, and request body into a signature string, then computing an HMAC-SHA256 hash using a secret key. For signature calculation, the request body MUST be canonicalized according to RFC 8785 (JSON Canonicalization Scheme) before performing any cryptographic signing operations.

Algorithm: HMAC-SHA256
Encoding: Base64
Signature Header: X-App-Signature

Signature Generation Process

Step 1: Extract Request Components

  1. URL: Extract the base URL (without query parameters)
  2. Query Parameters: Extract all enabled query parameters
  3. Request Body: Process the request body content

Step 2: Build Signature String

The signature string is constructed by concatenating the following components with & as separator:

signature_string = URL + "&" + sorted_query_params + "&" + request_body

2.1 URL Processing

  • Use the base URL without query parameters
  • Example: https://api.example.com/v1/orders

2.2 Query Parameters Processing

  • Extract all enabled query parameters
  • Sort parameters by key name (alphabetical order)
  • Format each parameter as key=value
  • Join multiple parameters with &
  • Handle null/undefined values as empty strings

Example:

Original parameters: {c: "3", a: "1", b: "2"}
Sorted result: a=1&b=2&c=3

2.3 Request Body Processing

  • JSON Format: Use JSON string directly
  • Null Value Handling: Empty objects {} or empty strings will be skipped
  • Type Conversion: Non-string types will be converted to JSON strings

Step 3: Calculate HMAC-SHA256 Signature

1. Use the constructed signature string as the message 2. Use the provided secret key 3. Calculate HMAC-SHA256 hash 4. Encode the result in Base64 format