Authentication Guide

By reading this guide, you can learn how to perform authentication operations when calling APIs

Authentication Note

1. Before API requests, you need to contact with our company to obtain your appId and appSecret
2. Please do not transmit appSecret over the network and do not store or use it on non server side
3. All services of this system are limited to server-side calls only. Please do not use them on the client side. If the system detects frequent changes in the IP records of your interface calls, it may trigger risk control
4. Once the appSecret is intercepted, it may cause your appId to unsafe. If this happens, it may lead to your appId being blocked
5. In order to prevent the request data of the interface from being intercepted during the Internet transmission, so as to carry out replay attacks, all interfaces of our server need to dynamically generate signatures to enhance security

---

Authentication parameters

Calling all open APIs requires authentication, and the parameters described below need to be correctly generated and carried during the request

Parameter Name	Parameter Type	Value Type	Note
X-CA-App-Id	header	string	Your appId
X-CA-Timestamp	header	string	Unix standard timestamp
X-CA-Nonce	header	string	Random number
X-CA-Signature	header	string	Signed HEX, please read the following document to learn how to generate a signature
X-CA-Signature-Method	header	string	An algorithm for hashing signatures

Note

• The value filled in by the parameter X-CA-Signature-Method needs to be supported by our server, otherwise an error will be returned. The error message will describe the list of signature methods supported by the server, which is the allowed value for this parameter to be passed in

• The parameter X-CA-Nonce supports the upper and lower limits of the maximum long type, with signed types. Every time an interface is called, this random value is recorded, and the next request will be rejected if the random number is the same.

• The parameter X-CA-Timestamp is filled in with the requester's current timestamp, which is also a Unix timestamp. Our server allows requests to arrive within a maximum of 30 seconds. If this time is exceeded, it will be considered invalid and the request will be rejected

---

How to generate a signature

1. Signature parameters: Random number, timestamp, and appSecret. The following is the pre signature concatenation method for these three parameters: X-CA-Nonce:X-CA-Timestamp:appSecret
2. For example: If the random number(X-CA-Nonce) is 1234, the timestamp(X-CA-Timestamp) is 4321, and the appSecret is 0000, then the final concatenated string is: 1234:4321:0000
3. Encoding signature: Hash the string in the above example to obtain HEX: 8459b52d89589d0cebeb827aeeed32aa9ae4d0a1

Example for generating signatures(Python):

def create_sign(time_stamp, nt, name):
    """
        Create a signature based on timestamp, random number, and appSecret, using the algorithm of the passed in name
    :param name: The hash method.
    :param time_stamp: Current unix timestamp
    :param nt: Random number
    :return: The result for the signed.
    """
    hash_obj = hashlib.new(name)
    hash_obj.update(f"{nt}:{time_stamp}:{appSecret}".encode(encoding="ascii"))
    return hash_obj.hexdigest()

signature_method = "SHA1"
signature_hex = create_sign(4321, 1234, "SHA1")
print(f"Sign by {signature_method}: {signature_hex}")

---

Note for security

Can appId be transmitted in plaintext?

Yes, appId is only used to indicate the identity information of the requester and will not cause any security related issues

Why can't appSecret be transmitted over the Internet or hard coded on the client?

appSecret is the primary security information of the calling interface. If this information is transmitted on the Internet, it may be stolen by eavesdropping. If it is hard coded on the client, it may be stolen by decompiling. If this appSecret is leaked, all requests for your appId may be simulated. When the risk control system on this server discovers an abnormal appId, it may impose control restrictions on it, And it caused your normal service to be interrupted.

How to handle the leakage of appSecret that is not my intention?

Quickly contact our company to temporarily ban the appId and change the appSecret. After changing the appSecret, our company will lift the temporary ban on the appId, and you can use the new appSecret to make a request.

---