合作伙伴 API（B2B）
身份验证
使用合作伙伴门户签发的 API 密钥进行身份验证，以及轮换、限制或吊销密钥的方法。
密钥格式#
text
esk_live_<prefix:10>_<secret:40>密钥由 10 位前缀（在门户中用于识别密钥的公开标识）与 40 位秘密值组成的字母数字字符串。esimoa 仅保存 SHA-256 哈希，因此完整密钥只在签发时显示一次，之后无法找回。
注意
与开发者中心的公开 API 密钥（esk_live_<32 位>）格式不同。混用到对方 API 会被 INVALID_API_KEY 拒绝。
发送密钥#
每个请求都通过 X-API-Key 请求头发送密钥，也支持 Authorization: Bearer。未发送密钥返回 401 API_KEY_REQUIRED，格式错误或不存在的密钥返回 401 INVALID_API_KEY。
http
# Preferred
X-API-Key: esk_live_AbCdE12345_<40-character secret>
# Also accepted
Authorization: Bearer esk_live_AbCdE12345_<40-character secret>签发密钥#
- 1合作伙伴门户 → API 密钥 — 创建新密钥。
- 2填写名称，并可选填过期时间（1 分钟后至 3 年内）与 IP 允许列表。
- 3立即复制仅显示一次的密钥，并保存到密钥管理工具或服务器环境变量中。
每个账号默认最多可同时拥有 5 个有效密钥（未吊销且未过期的密钥）。
轮换密钥#
轮换会创建名称、权限、IP 列表与过期时间相同的新密钥，旧密钥仅在您设定的宽限期（0–72 小时）内继续可用，之后过期。请在此期间部署新密钥。宽限期为 0 时旧密钥立即失效。
注意
已吊销或已过期的密钥无法轮换 — 请签发新密钥。宽限期结束后旧密钥会收到 401 KEY_EXPIRED。
IP 允许列表#
每个密钥最多可指定 20 个允许调用的 IPv4/IPv6 地址或 CIDR 网段（如 203.0.113.10、198.51.100.0/24）。留空表示不限制，列表外的请求返回 403 IP_NOT_ALLOWED。请填写服务器的出站（egress）IP。
吊销密钥#
密钥泄露或不再使用时，请立即在门户中吊销。密钥不做缓存，下一个请求起即返回 401 KEY_REVOKED。紧急情况下 esimoa 可吊销密钥或暂停账号，被暂停账号的所有密钥都会收到 403 PARTNER_SUSPENDED。
成员权限#
| 角色 | 可执行操作 |
|---|---|
| OWNER | 全部功能 |
| ADMIN | 管理密钥与成员 |
| DEVELOPER | 管理密钥、浏览商品 |
| VIEWER | 只读 |
仅 OWNER、ADMIN、DEVELOPER 可以签发、轮换或吊销密钥，所有成员均可查看密钥列表。