Signature Authentication Method

To provide more secure API authentication, we recommend using digital signature authentication for accessing interfaces. Digital signature authentication is a more secure alternative to using API keys alone. It involves encrypting a string derived from request parameters to authenticate identities.

Get API Token and API Secret through the dashboard

Authentication Instructions

To ensure the security and control of API usage, the caller needs to compute and add the following parameters in the HTTP request header based on the specific details of each request. The platform verifies these parameters, treating requests that fail validation as unauthorized.

Param	Description	Example
API-Token	API Token from API management page	L35ZD3K4AORZH7NVQBR9O
Algorithm	Encryption algorithm (supported: HMAC-SHA256, HMAC-SHA3_256)	HMAC-SHA256
Date	Current timestamp in ISO-8601 format	2024-06-17T00:00:00Z
Body-MD5	MD5 hash value of the non-GET request body (empty if absent).	a4e00bea676896c4524f112fd0e2f6b6
Signature	Base64-encoded signature information (calculated using a hash algorithm).	Please refer to the following Signature for the rule of generating.

Signature Specifies the rule for generating

On the Platform API Management Page, obtain the public_key and secret_key after enabling the signature authentication feature

	Description	Example
algorithm	Encryption algorithm (supported: `HMAC-SHA256`, `HMAC-SHA3_256`)	HMAC-SHA256
date	Current timestamp in ISO-8601 format	2024-06-17T00:00:00Z
request_info	HTTP method (uppercase), path, and request parameters (excluding domain).	GET /test/logs?size=20&page=2
body_md5	MD5 hash value of the non-GET request body (empty if absent).	a4e00bea676896c4524f112fd0e2f6b6

Generating the Signature parameter involves these steps:

Construct signature_origin:
signature_origin is formed by concatenating the following parameters using | as the delimiter: {algorithm} | {date} | {request_info} | {body_md5}

Example: HMAC-SHA256 | 2024-06-17T00:00:00Z | GET /test/logs?size=20&page=2

When body_md5 is absent: HMAC-SHA256 | 2024-06-17T00:00:00Z | POST /test/logs | a4e00bea676896c4524f112fd0e2f6b6

Generate signature_sha:
Calculate signature_sha using HMAC-SHA256 with secret_key:

signature_sha=hmac-sha256(signature_origin, secret_key)

Encode signature_sha:
Encode signature_sha using base64 to obtain the final signature:

`signature=base64(signature_sha)`

This yields the signature parameter.

Postman example

Signature Debugging Method

When API gateway signature verification fails, the server returns the original signing information. Users can compare it with their local signing information to identify the issue.

Compare signature_origin:

Ensure that both the server and client have the same signature_origin.

This includes the request method, path, parameters, and any other relevant data used in creating the signature_origin.

Check secret_key:

Verify that the secret_key used for signing on both the client and server sides is correct and identical.

Ensure there are no discrepancies or typos in the secret_key.

Error Information Analysis:

Pay close attention to the error messages returned by the API gateway.

The messages often contain specific details about what part of the signature verification failed.

Use these details to pinpoint whether the issue lies in the signature_origin, secret_key, or another part of the process.

Verify Algorithm and Encoding:

Confirm that the HMAC-SHA256 algorithm is implemented correctly.

Ensure that the raw bytes of signature_sha are correctly base64 encoded.

Ensure Consistency:

Check that the timestamp is in ISO-8601 format and synchronized between client and server.

Verify that the MD5 value of the request body is correctly calculated and formatted as an uppercase hexadecimal string.

Ensure that the request method, path, and parameters are correctly concatenated without including the domain name.

Log Intermediate Values:

Implement logging to capture intermediate values for signature_origin, signature_sha, and the final signature.

Compare these logs between client and server to identify discrepancies.

By following these steps and utilizing the error messages provided by the API gateway, you can effectively debug and resolve issues related to signature verification.

Signature Authentication Method

Authentication Instructions#

Signature Specifies the rule for generating#

Postman example#

Signature Debugging Method#

Authentication Instructions

Signature Specifies the rule for generating

Postman example

Signature Debugging Method