Webhook 署名シークレットの更新

POST

/api/v1/webhook/rotate-secret

中国本土のユーザー向け: 中国本土のユーザーは https://api.toapis.cn を API エンドポイント (Base URL)としてご利用ください. 本ドキュメント内の例では https://api.toapis.com を https://api.toapis.cn に置き換えてください.

動作

指定キーの署名シークレットを生成または更新します. 受信側はこれでコールバック署名を検証します. ローテーション自体ではコールバックは有効になりません. secret はこのレスポンスに一度だけ返り, GET では再発行できないため, 紛失時は再度ローテーションしてください. 旧シークレットはローテーション後 24 時間, 検証の過渡用に有効です.

旧スロットは 1 つのみで, 連続ローテーションで置き換わります.

削除済みまたは 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, 対象キーが存在しないか他人のものは 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 設定の取得を参照してください.