輪換 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 生命週期寫入操作共用: 同一帳號每分鐘最多 10 次寫請求. JSON 最多 16384 位元組, 本文讀取期限 10 秒, 拒絕查詢參數, 未知或重複 JSON 欄位. 必須明確提供 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 設定.