API鉴权指南

阅读本指南，您可以了解如何在调用API时进行鉴权操作

注意事项

1. 在进行API调用之前，你需要与本公司进行合作，获取你的appId和appSecret
2. appSecret请勿在网络中传输，请勿在非服务器端存放与使用
3. 本系统所有服务仅限于服务器端调用，请勿在客户端使用，当系统发现你的接口调用的ip记录频繁变化时，可能会触发风控
4. appSecret一旦被截取可能会导致你的appId产生接口盗刷，如果出现此情况，可能会导致你的appId被封控
5. 为了防止接口的请求数据在互联网传输时被监听拦截，从而进行重放攻击，我司服务端所有的接口都需要动态生成签名以加强安全性

---

鉴权参数

调用所有的开放api都需要鉴权，以下描述的参数需要在请求的时候正确生成与携带

参数	参数类型	值类型	备注
X-CA-App-Id	header	string	你的appId
X-CA-Timestamp	header	string	unix标准时间戳
X-CA-Nonce	header	string	随机数
X-CA-Signature	header	string	请阅读下方文档了解如何生成签名
X-CA-Signature-Method	header	string	对签名进行hash化的算法

可能存在的误区

• 参数 X-CA-Signature-Method 所填写的值需要我司服务端支持，否则将返回错误，错误信息中会描述服务端支持的签名方法列表，也就是此参数允许传入的值

• 参数 X-CA-Nonce 最大支持 long 类型的上下限，有符号类型。每次调用一个接口都会记录此随机数值，下次请求如果随机数相同会拒绝请求。

• 参数 X-CA-Timestamp 填入的是请求者的当前时间戳，也是unix时间戳，我司服务端最多允许请求在30S内到达，超过此时间将认为该请求已失效而拒绝该请求

---

签名如何生成？

1. 签名参数：随机数、时间戳、appSecret三个参数，以下是它们三者的签名前的拼接方法随机数:时间戳:appSecret
2. 举个例子：随机数是1234，时间戳是4321，appSecret是0000，那么最终拼接出来的字符串就是1234:4321:0000
3. 得到签名：对上述的例子中的字符串进行sha1散列化得到HEX为8459b52d89589d0cebeb827aeeed32aa9ae4d0a1

签名的生成的示例代码（Python）：

def create_sign(time_stamp, nt, name):
    """
        根据时间戳和随机数和appSecret创建签名，使用传入的名称的算法
    :param name: 签名算法名称
    :param time_stamp: 时间戳
    :param nt: 随机数
    :return: 签名结果
    """
    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}")

---

安全事项

appId可以明文传输吗？

可以，appId只是用于标志请求者的身份信息，不会导致任何的安全相关的问题

appSecret为什么不可以在互联网中传输或者是硬编码在客户端中？

appSecret是调用接口的首要安全信息，此信息如果在互联网中传输有被监听窃取的风险，如果硬编码在客户端中则有被反编译窃取的风险。 如果此信息被泄露，你的appId所有的请求都可能会被模拟，当本服务端风控系统发现appId异常时，可能会对其进行管控限制， 而导致你的正常服务被中断。

非本人意愿的appSecret泄露如何处理？

迅速联系我司进行appId的临时封禁与appSecret的更改，在更改appSecret之后我司再解除appId的临时封禁，你再使用新的appSecret进行请求。

---