认证机制

Token 格式

Agent Token 采用三段式结构，各部分以 . 分隔：

{agent_api_key}.{timestamp}.{signature}

部分	类型	说明	示例
agent_api_key	string	您的 API Key	a9f3c28d7b1e4f90c2a1b3d4
timestamp	string	当前 Unix 时间戳（秒）	1743055200
signature	string	HMAC-SHA256 签名（hex 小写）	a1b2c3d4e5...

签名算法

signature = HMAC-SHA256(agent_api_key + "." + timestamp, agent_api_secret) → hex 小写

生成步骤

1. 获取当前时间戳
   Unix timestamp（秒），如 1743055200

2. 拼接待签名字符串

   raw_string = agent_api_key + "." + timestamp

3. 计算 HMAC-SHA256 签名

   signature = HMAC-SHA256(raw_string, agent_api_secret)

   转为 hex 小写字符串

4. 组合 Token

   token = agent_api_key + "." + timestamp + "." + signature

5. 放入 HTTP Header

   Authorization: Bearer {token}

时效性

Token 中的时间戳必须在服务器当前时间 ±2 分钟 以内，否则会被拒绝。请确保您的服务器时间准确（建议使用 NTP 同步）。

服务端验证流程

服务端收到请求后的验证步骤：

1. 提取 Token — 从 Authorization: Bearer {token} Header 中获取 Token
2. 拆分 Token — 按 . 分割为 agent_api_key、timestamp、signature 三部分
3. 验证时间戳 — 确认 timestamp 与服务器时间差不超过 2 分钟
4. 查库获取密钥 — 用 agent_api_key 查数据库取出 agent_api_secret
5. 验证签名 — 用取到的 agent_api_secret 重新计算 HMAC-SHA256 并比对 signature

双向签名验证 (Mutual Verification)

为确保接口的安全性，系统对双向调用的认证机制进行了如下定义：

1. Agent 调用 VCT 平台（API 接口）：Agent 需按照上述步骤生成 Token 并携带在 Authorization: Bearer {token} 请求头中，由 VCT 平台进行验证。
2. VCT 平台调用 Agent（回调接口/Webhook）：VCT 平台向 Agent 发送余额查询、下注扣款、结算派彩、下注取消或数据推送等回调请求时，不携带 Authorization 请求头。包网系统仅需要对请求体中的参数签名进行校验，验签算法如下：
   • 对于普通回调（如 /balance、/bet、/settle、/cancel）： signature = HMAC-SHA256(username + "." + timestamp, agent_api_secret)
   • 对于投注数据推送（/bet-push）： signature = HMAC-SHA256(agent_api_key + "." + timestamp, agent_api_secret) 包网系统校验请求体中的 sign 字段与上述算法计算结果一致即可。