指南

快速入門

使用 RunAPI 管理金鑰建立並管理標準 API 金鑰與防護欄。

平台管理讓帳戶管理員無需透過儀表板即可建立、檢查、更新及撤銷標準 API 金鑰與防護欄。

建立管理金鑰

請遵循身分驗證指南登入，然後開啟管理金鑰頁面並建立管理金鑰。請將其與標準應用程式金鑰分開存放。僅以 Bearer 權杖方式傳送至平台管理端點。

HTTP

Authorization: Bearer YOUR_MANAGEMENT_KEY

標準 API 金鑰無法呼叫金鑰或防護規則管理端點。有效的管理金鑰在其擁有者不再具備所需帳戶角色時，仍可能收到 403 Forbidden。

列出標準 API 金鑰

使用 GET /api/v1/keys 檢視管理金鑰帳戶下可見的金鑰：

SHELL

curl "https://runapi.ai/api/v1/keys" \
  -H "Authorization: Bearer YOUR_MANAGEMENT_KEY"

使用回傳的公開識別碼進行後續的擷取、更新、撤銷或護欄指派請求。切勿根據金鑰名稱或遮罩權杖來推斷存取權限。

建立與輪換金鑰

使用 POST /api/v1/keys 建立應用程式金鑰。完整密鑰僅在建立回應中返回一次，因此請在捨棄該回應前將其儲存至您的密鑰管理員。金鑰輪換流程應包含：建立替代金鑰、部署至應用程式、驗證流量，然後撤銷舊金鑰。

SHELL

curl -X POST "https://runapi.ai/api/v1/keys" \
  -H "Authorization: Bearer YOUR_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Production worker"}'

credit_limit_windows 接受 1h、1d 及 7d 滾動消費上限的任意組合。若任一已設定的視窗已耗盡，使用該金鑰的呼叫將回傳 429 Too Many Requests，直到使用量離開該視窗為止。更新金鑰時傳送空物件可清除所有滾動上限。

套用防護規則

Guardrails 是可重複使用的帳號政策，用於模型、提供者及消費控管。請透過 /api/v1/guardrails 管理政策，再使用 /api/v1/guardrail_assignments 附加或移除 Guardrail。若 assignment 遭拒，應視為政策或擁有權問題，而非在缺少 Guardrail 的情況下靜默繼續執行。

處理管理錯誤

401 Unauthorized 表示憑證遺失、格式錯誤、已撤銷或無效。
403 Forbidden 表示憑證類別或帳戶角色無法執行該操作。
404 Not Found 表示所請求的資源對已驗證身分的帳戶不可見。
422 Unprocessable Content 表示一個或多個提交的值違反了資源規則。