API Token 换取与使用指南

API Token 适用于平台类客户或服务器间（S2S）调用场景。调用方先使用 API Key 换取短期 STS Token，再通过 Bearer Token 访问受保护接口。

接入流程

准备 CITV 分配的 AccessKeyId 和 SecretAccessKey。
调用 POST /api/auth/api-token 换取短期 STS Token。
后续业务接口统一携带 Authorization: Bearer <token>。
Token 到期后重新换取；新 Token 不会让旧 Token 立即失效。

接口概览

项目	说明
端点	`POST /api/auth/api-token`
鉴权方式	API Key 请求头
限流	每会话 120 秒内 60 次、每 IP 120 秒内 60 次
响应结构	`{ code: number, data: { token, expiresAt, scope }, message?: string }`

API Key 支持以下任一请求头格式：

x-api-key: <AccessKeyId>:<SecretAccessKey>

Authorization: ApiKey <AccessKeyId>:<SecretAccessKey>

请求体参数

字段	类型	必填	说明
`ttlSeconds`	number	否	指定令牌有效期，单位秒
`scope`	string[]	否	指定权限范围，必须是白名单内的子集
`platformCompanyId`	string	否	指定目标平台公司 ID，推荐使用
`platformCode`	string	否	指定目标平台代码，适合人工可读场景

`ttlSeconds`

项目	说明
默认值	`API_TOKEN_TTL_SECONDS`，未配置时为 1800 秒（30 分钟）
最小值	30 秒
最大值	`API_TOKEN_TTL_MAX_SECONDS`，未配置时为 3600 秒（1 小时）
建议	按业务所需设置最短有效期，推荐 15–30 分钟

`scope`

scope 用于限制本次 Token 的权限范围。若不传 scope 字段，默认使用 Access Key 可用权限；未配置 Key 级权限时使用系统白名单。

显式传入空数组 scope: [] 会返回 400。

可用 scope：

Scope	用途
`company:list`	鉴权检查
`cert:read`	证书读取
`merchant:register`	创建商户
`merchant:update`	更新商户
`merchant:read`	查询商户
`merchant:delete`	删除商户
`domain:create`	创建域名
`domain:update`	更新域名
`domain:read`	查询域名详情、商户域名列表、当前平台域名配额快照
`domain:delete`	删除域名

平台选择参数

当当前用户仅绑定一个 active 平台时，可以不传平台选择参数。若绑定多个 active 平台，建议显式传入 platformCompanyId，避免歧义。

字段	说明	兼容别名
`platformCompanyId`	目标平台公司 ID，推荐自动化脚本使用	`platformId`、`platform_company_id`、`platform_id`
`platformCode`	目标平台代码，人工可读字段	`tenantCode`、`tenant_code`

如果同时传入 platformCompanyId 与 platformCode，两者必须指向同一平台，否则返回错误。

响应数据

字段	类型	说明
`token`	string	短期令牌字符串，HMAC-SHA256 签名的轻量 JWT
`expiresAt`	number	过期时间，Unix 时间戳，单位秒
`scope`	string[]	实际生效的权限列表，已按白名单过滤
`platformCompanyId`	string	实际绑定的平台公司 ID
`platformCode`	string	实际绑定的平台代码

成功响应示例：

{
  "code": 200,
  "data": {
    "token": "eyJhbGciOi...",
    "expiresAt": 1732173600,
    "scope": ["domain:read"],
    "platformCompanyId": "67c93f...",
    "platformCode": "tenant-a"
  },
  "message": "OK"
}

使用方式

将换取到的 Token 作为 Bearer 令牌随请求发送：

Authorization: Bearer <token>

服务器端会通过 verifyApiToken 验证签名与过期时间，并提取载荷用于权限控制。

调用示例

1. 换取 Token

curl -X POST \
  -H "Content-Type: application/json" \
  -H "x-api-key: AKID1234567890:SAKabcdef..." \
  -d '{"ttlSeconds":1800,"scope":["domain:read"],"platformCompanyId":"67c93f..."}' \
  https://<your-host>/api/auth/api-token

2. 携带 Token 调用受保护接口

curl -H "Authorization: Bearer eyJhbGciOi..." \
  https://<your-host>/api/v1/...

例如查询当前平台域名配额快照：

curl -H "Authorization: Bearer eyJhbGciOi..." \
  https://<your-host>/api/v1/domains/quota

过期与刷新

新换取的 Token 不会使旧 Token 失效。
旧 Token 在到达自身 exp 之前仍然有效。
客户端应在 Token 过期前主动刷新，避免业务请求因过期失败。
不建议为每个业务请求都重新换 Token，应按 TTL 缓存复用。

常见错误

HTTP / code	场景	处理建议
400	当前用户绑定多个 active 平台但未传平台选择参数；`platformCompanyId` 与 `platformCode` 不匹配；显式传入空 `scope`	检查请求体参数
401	缺少或无效的 API Key；密钥状态非 active；Secret 校验失败	检查 API Key 与密钥状态
403	指定平台不属于当前用户；目标平台不可用；请求的 scope 不在白名单内；超出 Access Key 授权范围	缩小 scope 或检查平台归属
429	触发限流	在约 120 秒窗口内控制调用频率，使用退避重试
500	参数解析或服务端异常	查看 `message` 获取具体信息

安全建议

将 TTL 控制在业务所需的最小范围，推荐 15–30 分钟。
将 scope 仅授权必要权限的子集，避免使用全量白名单。
SecretAccessKey 只应保存在服务端，不要下发到浏览器或移动端。
日志中不要打印完整 API Key、Secret 或 Bearer Token。
如果怀疑密钥泄露，应立即禁用或轮换 Access Key。

API Token 换取与使用指南

On this page