跳至主要內容
指南
指南

快速入門

使用 RunAPI 管理金鑰建立並管理標準 API 金鑰及安全護欄。

檢視 Markdown

平台管理讓帳號管理員無需為每次變更登入儀表板，即可建立、查閱、更新及撤銷標準 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","tags":["env:production","dept:ml","project:chatbot"]}'

credit_limit_windows 接受 1h、1d 和 7d 滾動消費上限的任意組合。如果任何已設定的窗口耗盡，使用該金鑰的呼叫將返回 429 Too Many Requests，直到使用量離開該窗口。 更新金鑰時發送空物件以清除所有滾動上限。

當建立請求省略所有開支限額欄位及 guardrail_id 時，新金鑰會使用工作空間的治理預設值。明確指定的限額、滾動視窗或防護規則會取代該預設選項。傳送 credit_limit_cents: null 即可建立無限額的原生限額。指定金額但未提供重設週期時，仍會使用終身限額。更新操作不會重新套用工作空間預設值，修改預設值亦不會變更現有金鑰。

Key 標籤

建立及更新接受 tags，即完整 key:value 字串陣列。列表、讀取、建立及更新回應會返回完整陣列。PATCH 會取代陣列；省略 tags 則保留原值。key 長度為 1–32 個字元，value 為 1–64 個字元，恰好一個冒號且不能有空白字元。最多 20 個不同標籤，包含預設標籤。格式錯誤或預設值衝突會返回 422 及標籤驗證錯誤；非陣列或非字串元素會返回 400。

必須且只能有一個用途標籤：usage:developer 或 usage:service。Management API 建立時若未提供用途，包含 tags: []，會加入 usage:service。Dashboard 建立及未提供用途的標籤更新使用 usage:developer。現有 Key 以 Developer 遷移。環境可省略，最多接受 env:production、env:staging、env:dev 之一（不接受 env:prod）。

Dashboard 建立／編輯提供用途、環境快捷選項、自訂標籤，以及只來自目前工作區未刪除標準密鑰的建議。列表顯示標籤值，滑鼠停留時顯示完整標籤。標籤不會改變密鑰擁有權、可見範圍或權限。標籤可將密鑰連繫至共用標籤預算。

成員必帶標籤

工作區管理員在 Team 的成員預算表單中設定成員必帶標籤。必帶標籤是區分大小寫的自訂標籤，例如 team:growth。usage: 及 env: 命名空間已保留。每位成員最多可有 19 個必帶標籤，而每個密鑰仍受總共 20 個標籤的上限限制。

每個新標準密鑰都會自動包含其擁有人在該工作區的必帶標籤。建立時會先合併提交的標籤與必帶標籤，再進行驗證。例如，成員須帶有 team:growth 時，Management API 建立請求傳入 tags: ["project:chatbot"]，回應會包含 project:chatbot、team:growth 及預設的 usage:service。

明確提供 tags 的 PATCH 必須保留所有必帶標籤。即使呼叫者是管理員，移除必帶標籤也會返回 422，驗證錯誤會列出缺少的標籤。省略 tags 會保留密鑰原有標籤。成員仍可新增或移除一般標籤。

管理員須在 Team 修改成員設定，才能撤銷必帶標籤。儲存設定後，該成員所有現有標準密鑰都會補上新必帶標籤，並移除已撤銷的必帶標籤，其他標籤則保留。這包括已停用和過期的密鑰，但不包括已刪除的密鑰。若任何密鑰無法接受最終標籤組合，整個儲存會失敗，表單會指出需要修正的密鑰。

標籤預算使用每個密鑰目前的標籤。修改必帶標籤也會改變本期既有支出的預算歸屬。新增必帶標籤可能立即耗盡該標籤的預算。現有成員的必帶標籤預設為空，管理員儲存設定前，其密鑰維持不變。

套用防護欄

Guardrails 是可重複使用的帳戶政策，用於模型、供應商及消費控制。透過 /api/v1/guardrails 管理政策，然後使用 /api/v1/guardrail_assignments 來附加或移除它們。將被拒絕的指派視為政策或所有權失敗，而非在沒有 guardrail 的情況下靜默繼續。

處理管理錯誤

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

共享標籤預算

建立總額為正的 block 模式 Guardrail，再分配其 guardrail_id 和區分大小寫的 tag，例如 dept:ml。api_token_id、account_user_id 或 tag 只能選擇一個。標籤預算要求管理員權限。停用的預算不執行限制。管理請求不消耗預算。

預算按標準金鑰目前標籤彙總，包含已刪除、停用和到期金鑰的花費。新增或移除標籤會移動該金鑰當期花費。建立或重建預算不會清零。金鑰數量排除已刪除金鑰。所有符合的預算都必須允許請求；拒絕時傳回 403 和標籤名稱。

credit_limit_reset_interval 為 null 表示終身限制，其他週期使用 UTC。提示門檻預設為 80，接受 1 至 100。直接更新 Guardrail 會影響所有分配；控制台編輯標籤預算時會先複製策略。

准入會檢查預留金額。結算可能超過預留，顯示超過 100% 的使用率，並封鎖後續付費請求。日誌使用日誌建立時間；待處理任務與批次使用各自建立時間。較早週期受理的任務可能在較晚週期結算。