轮换 API Key | ToAPIs Documentation

POST

/api/v1/api-keys/{api_key_id}/rotate

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

使用说明

为指定 Key 生成一把新密钥, 用于密钥泄露或定期轮换场景. 成功时返回完整的 key, 原 ID, 名称, 状态, 到期时间, 额度和限制都保持不变. 停用, 过期或已耗尽的 Key 也可以轮换, 但轮换不会自动启用它. 已吊销的 Key 返回 404. 轮换成功后旧密钥立即失效, 没有新旧密钥同时可用的过渡期.

如果对同一 Key 并发发起多个轮换, 只有最后提交的密钥有效, 其余立即作废, 所以请串行执行轮换.

鉴权

Authorizationstring请求头必填

系统访问令牌, 格式为 Bearer YOUR_SYSTEM_ACCESS_TOKEN. 不接受模型 Key, 无需 X-User-Id. 共用规则见接入方式.

请求参数

api_key_idstring路径必填

自有普通模型 Key 的十进制 ID 字符串, 不是 sk- 密钥.

非空请求体要求 Content-Type: application/json, 最大 16384 字节. 顶层必须是 JSON 对象, 拒绝未知字段, 重复字段和查询参数. 写请求有 10 秒正文读取期限.

请求体只能为空或 {}.

请求示例

curl --request POST \
  --url 'https://api.toapis.com/api/v1/api-keys/43/rotate' \
  --header 'Authorization: Bearer YOUR_SYSTEM_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{}'

import requests

response = requests.post(
    "https://api.toapis.com/api/v1/api-keys/43/rotate",
    headers={"Authorization": "Bearer YOUR_SYSTEM_ACCESS_TOKEN"},
    json={},
    timeout=30,
)
response.raise_for_status()
print(response.json())

const response = await fetch("https://api.toapis.com/api/v1/api-keys/43/rotate", {
  method: "POST",
  headers: { Authorization: "Bearer YOUR_SYSTEM_ACCESS_TOKEN", "Content-Type": "application/json" },
  body: JSON.stringify({}),
  signal: AbortSignal.timeout(30_000),
});
if (!response.ok) {
  throw new Error(`HTTP ${response.status}: ${await response.text()}`);
}
console.log(await response.json());

响应字段

示例使用虚构数据. Key 元数据字段见获取 API Key 详情, 通用响应和错误处理见接入方式.

data.keystring

完整密钥, 已包含 sk- 前缀, 只在本次创建或轮换响应中返回.

响应示例

{
  "code": 0,
  "message": "",
  "data": {
    "id": "43",
    "name": "Example Key",
    "key_hint": "****new4",
    "status": "enabled",
    "created_at": "2026-11-01T08:00:00Z",
    "expires_at": "2027-01-01T00:00:00Z",
    "unlimited": false,
    "remaining_credits": "500",
    "daily_limit_credits": null,
    "monthly_limit_credits": null,
    "key": "sk-example11111111111111111111111111111111111111new4",
    "model_limits": [],
    "allow_ips": []
  }
}