輪替 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": []
  }
}