轮换 Webhook 签名密钥 | ToAPIs Documentation

POST

/api/v1/webhook/rotate-secret

国内用户请注意: 中国大陆用户请使用 https://api.toapis.cn 作为接口地址 (Base URL). 文档示例中的 https://api.toapis.com 请替换为 https://api.toapis.cn.

使用说明

为指定 Key 生成或更换验签密钥 (secret), 接收端用它验证回调签名. 轮换本身不会启用回调. secret 只在本次响应中返回一次, GET 接口无法补发; 丢失后需要再次轮换. 上一条密钥在轮换后保留 24 小时用于验签过渡, 只保留一个旧密钥槽位, 连续轮换会替换它.

写操作不能用于已软删除或带 scope 的 Key; Key 停用, 过期或额度耗尽不影响配置管理. 限流与 Key 生命周期写操作共用: 同一用户每分钟最多 10 次写请求. 请求 JSON 顶层必须是对象, 最多 16384 字节, 正文读取期限 10 秒; 不接受查询参数, 未知字段或重复字段. 请求必须显式提供 api_key_id.

鉴权

Authorizationstring请求头必填

使用系统访问令牌, 格式为 Bearer YOUR_SYSTEM_ACCESS_TOKEN, 只能访问当前账号自己的数据. 不接受模型 Key, 无需 X-User-Id, 也没有管理端或团队旁路.

请求参数

api_key_idinteger请求体必填

自有普通模型 Key 的正整数 ID (不是 sk- 密钥或系统访问令牌). JSON 中必须是整数, 不接受字符串, null, 省略或查询参数.

api_key_id 无效返回 400; 目标 Key 不存在或属于他人统一返回 404; mode=off 禁止密钥管理, 返回 409 (code=16016); 触发限流返回 429.

请求示例

curl --request POST \
  --url 'https://api.toapis.com/api/v1/webhook/rotate-secret' \
  --header 'Authorization: Bearer YOUR_SYSTEM_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{"api_key_id":123}'

响应示例

{
  "code": 0,
  "message": "",
  "data": {
    "api_key_id": 123,
    "secret": "0000000000000000000000000000000000000000000000000000000000000000",
    "previous_secret_expires_at": null
  }
}

首次接入顺序与签名验签说明见查询 Webhook 配置.