API Key 管理
Token 格式、建立流程、8 個權限範圍（scopes）、生命週期、用量分析、安全最佳實務。
API Key 是您與 Braidrun 開放平台對話的唯一憑證。每個 Key 攜帶一組 scope（權限範圍）和一個 Token，丟失或洩漏時立即吊銷新建。
Token 格式
text
dyk_<id>_<secret>
例：dyk_a3b9c8d7e6f5a1b2_AbCdEfGhIjKlMnOpQrStUvWxYz0123456789dyk_— 品牌前綴，讓 git secret-scanning / 日誌脫敏工具可識別<id>— 16 字元 base62 公開 ID，可用作 lookup key（非敏感）<secret>— 32 位元組隨機 secret，base64url 編碼（敏感，不得上傳日誌 / 報錯訊息）
Token 只展示一次
產生 API Key 時，原始 Token 只在建立對話方塊中展示一次。關閉後服務端只保留 Argon2id 哈希，無法回查原文。請立即複製儲存到您的金鑰管理工具（1Password / Vault / Doppler / GitHub Secrets / etc）。
建立 API Key
- 存取 控制台 → 帳號設定 → API 金鑰
- 點選“新 API Key”
- 填入：名稱（用於辨識）、scope 清單、有效期限（永久 / 30 天 / 90 天 / 1 年）
- 點選「產生金鑰」→ 立即複製 Token
權限範圍（Scopes）
Scope 是細粒度權限，共 8 個：7 個可自助授予，CLUSTER_ADMIN 僅限管理員。給一把 Key 授予的越少越好，遵循最小權限原則。
| Scope | 能做什麼 | 典型場景 |
|---|---|---|
WEBHOOK_TRIGGER | 觸發綁定到該 Key 的 Webhook | GitHub Push → 工作流程；上游業務系統回調 |
APPROVAL_RESPOND | 批准 / 拒絕 manual_approval 步驟 —— 涵蓋審批 Webhook 與 v1 審批端點（/api/v1/approvals/*，含列出待審批、讀取詳情、提交編輯後的審批表） | 郵件 / Slack 一鍵審批連結；外部審批系統對接 |
WORKFLOW_READ | 列出 / 讀取工作流程定義 | 在外部 dashboard 中展示目前工作流程列表 |
WORKFLOW_EXECUTE | 透過 API 啟動工作流程（替代 Webhook 模式） | SDK 整合；自動化測試；批次任務 |
EXECUTION_READ | 查詢執行狀態 / 讀取完整 result | 回流執行結果到企業 BI / 資料倉儲 |
EXECUTION_CANCEL | 取消運行中的執行 | 管理面板的「停止」按鈕 / 緊急熔斷 |
ARTIFACT_READ | 列出執行產物 / 取得下載鏈接 | 歸檔報表到物件儲存；推送結果到下游系統 |
CLUSTER_ADMIN | 管理員專用：讀取叢集狀態、管理自動擴縮容策略。只有管理員能授予；非管理員建立 Key 時，該 scope 會被自動剝離 | 私有化部署的維運服務帳號 |
生命週期
- 創建 — 用戶自助；scope + 有效期限由您決定
- 使用 — 每次成功呼叫都會自動累積用量並更新 lastUsedAt 時間戳
- 吊銷 — 使用者隨時可在「API 金鑰」頁點「吊銷」；冪等
- 過期 — expiresAt 一到立即失效；不需主動吊銷
用量分析
每個 Key 在「API 金鑰」表格裡點「使用情況」會彈出圖表分析：
- 累計呼叫次數 + 視窗內（7/30/90/180 天可選）
- 高峰日（哪一天調用最多）
- 每日呼叫次數折線圖
- 呼叫端點分佈餅圖（webhook.trigger / workflow.execute / etc）
- 最近一次使用時間
用量僅統計成功反應（HTTP 2xx）。鑑權失敗 / 速率限制的請求不計入。
金鑰安全最佳實踐
請遵守
- 每個環境（生產 / 預發 / 本地）使用獨立 Key —— 出事時只吊銷受影響的環境
- 每個外部整合方使用獨立 Key —— 用「使用情況」看哪個整合在用
- 永遠不要把 Token 提交到程式碼倉庫
- 在 CI/CD 中以加密 Secret 形式註入；不要列印到日誌
- 觀察到「最近使用」時間和您預期不符 → 立即撤銷並檢查日誌
- 給短期合作夥伴的 Key 務必設定 expiresAt（建議 90 天以內）