快速入門

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

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

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

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

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

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

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

建立與更新接受 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。既有金鑰以 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。若 assignment 遭拒，應視為政策或擁有權問題，而非在缺少 Guardrail 的情況下靜默繼續執行。

建立總額為正的 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% 的使用率，並封鎖後續付費請求。日誌使用日誌建立時間；待處理任務與批次使用各自建立時間。較早週期受理的任務可能在較晚週期結算。