API 认证机制
更新时间 2026-04-29 10:25:48
最近更新时间: 2026-04-29 10:25:48
每次 API 请求均需在 HTTP Header 中携带完整的鉴权信息。认证机制包含两套签名，需同时传入：
业务签名（X-HMAC-SIGNATURE）：基于公私钥对请求进行业务级签名验证。
EOP 平台签名（Eop-Authorization）：天翼云 EOP 平台标准认证签名，基于 AK/SK 与请求信息动态生成。
请求消息头（完整列表）
| 参数名 | 是否必填 | 说明 | 示例值 |
|---|---|---|---|
| Content-Type | 是 | 消息体类型 | application/json |
| accountid | 是 | 租户 ID | tenant001 |
| X-APP-CODE | 是 | 应用编码（即AK） | your-app-code |
| X-REQUEST-DATE | 是 | 当前毫秒级时间戳 | 1713600000000 |
| X-HMAC-SIGNATURE | 是 | 业务签名：使用privateKey对message做 HMAC-SHA256 后再 Base64 编码 | Base64(HMAC_SHA256(privateKey, message)) |
| ctyun-eop-request-id | 是 | 请求流水号，32 位随机 UUID | 0ffb9b07-d5a8-4e19-b3ce-12dfb9705a1d |
| Eop-date | 是 | 请求时间，格式yyyyMMdd'T'HHmmss'Z'，使用北京时间（UTC+8），TZ 仅为格式符号 | 20221107T093029Z |
| Eop-Authorization | 是 | EOP 平台认证签名信息 | 见下方生成说明 |
业务签名（X-HMAC-SIGNATURE）生成方法
message 构造格式：
message = publicKey + "|" + X-REQUEST-DATE签名算法（Java 示例）：
importcn.hutool.crypto.digest.HMac;
importcn.hutool.crypto.SecureUtil;
importcn.hutool.core.codec.Base64;
String publicKey ="your-public-key";// 从控制台应用管理获取
String privateKey ="your-private-key";// 从控制台应用管理获取，请勿泄露
long time =System.currentTimeMillis();// 当前毫秒时间戳，即 X-REQUEST-DATE
String message = publicKey +"|"+ time;
HMac hMac = SecureUtil.hmacSha256(privateKey);
String xHmacSignature = Base64.encode(hMac.digest(message));
// Header 中传入：
// X-REQUEST-DATE: time
// X-HMAC-SIGNATURE: xHmacSignature签名算法（Python 示例）：
import hmac
import hashlib
import base64
import time
public_key ="your-public-key"
private_key ="your-private-key"
timestamp =str(int(time.time() *1000))# 毫秒时间戳
message = public_key +"|"+ timestamp
x_hmac_signature = base64.b64encode(
hmac.new(
private_key.encode("utf-8"),
message.encode("utf-8"),
hashlib.sha256
).digest()
).decode("utf-8")EOP 平台签名（Eop-Authorization）生成方法
Eop-Authorization是天翼云 EOP 平台的标准认证机制，需按以下四个步骤依次构造。
步骤一：构造待签字符串（sigture）
sigture = <排序后的Header组合列表> + "\n" + <encoded的Query> + "\n" + <toHex(SHA256(body))>各部分说明：
| 部分 | 构造规则 |
|---|---|
| 排序后的Header组合列表 | 将需要签名的Header（必须包含ctyun-eop-request-id和eop-date）以header_name:header_value的形式，按 header_name 字母表顺序排序，每个 Header 以\n结尾拼接在一起 |
| encoded 的 Query | 将 URL 的 Query 参数以key=value的形式、以&拼接，value 需要 URL encode；无 Query 参数时为空字符串 |
| toHex(SHA256(body)) | 对请求 body 做 SHA256 摘要，将结果转十六进制字符串 |
sigture 示例（Query 为空时）：
ctyun-eop-request-id:27cfe4dc-e640-45f6-92ca-492ca73e8680\neop-date:20220525T160752Z\n\n\ne3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855sigture 示例（Query 不为空时，如aa=1&bb=2）：
ctyun-eop-request-id:27cfe4dc-e640-45f6-92ca-492ca73e8680\neop-date:20220525T160930Z\n\naa=1&bb=2\ne3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855步骤二：构造动态密钥（kdate）
使用eop-date、AK（X-APP-CODE）、SK（privateKey）逐步推导动态密钥：
| 步骤 | 计算公式 | 说明 |
|---|---|---|
| 计算 ktime | ktime = HMAC-SHA256(eop-date, SK) | 以 SK 为密钥，对 eop-date 做 HMAC |
| 计算 kAk | kAk = HMAC-SHA256(AK, ktime) | 以 ktime 为密钥，对 AK 做 HMAC |
| 计算 kdate | kdate = HMAC-SHA256(eop-date的年月日, kAk) | 以 kAk 为密钥，对 eop-date 的年月日（如20220525）做 HMAC |
其中eop-date格式为yyyyMMddTHHmmssZ（北京时间，Z仅为格式符号）。
步骤三：计算 signature
signature = Base64( HMAC-SHA256(sigture, kdate) )步骤四：构造 Eop-Authorization
Eop-Authorization: {AK} Headers={headers_list} Signature={signature}| 部分 | 说明 |
|---|---|
| {AK} | 即 X-APP-CODE 的值 |
| Headers={headers_list} | 参与签名的 Header 名称以;分隔，按字母表排序，例如Headers=ctyun-eop-request-id;eop-date |
| Signature={signature} | 步骤三计算所得的 Base64 签名值 |
完整示例：
Eop-Authorization: 4a4bdc57e06542199b5f98d4cd107be2 Headers=ctyun-eop-request-id;eop-date Signature=b2WEo4nh9ewn6SWOP0ii5g8L0z9CT5gprpDWntlCX9I=注意： AK、Headers=、Signature=三部分之间以空格分隔。Eop-date的有效期为15 分钟，超期将导致鉴权失败，请确保请求端时钟准确。
