API Key

API Key 是客戶端呼叫 Hakila Gateway 的唯一憑證。

特性

• 明文只在建立時顯示一次；伺服器只存 SHA-256 hash
• 顯示用前綴（例如 sk-hakila-xxxx）方便辨識
• 可停用（Enabled = false）立即失效
• 可設定到期時間與預算（Admin 以 NTD 設定，Gateway 內部以 USD 累計）
• 隸屬 Workspace；可選綁定組織單位（UnitId）與／或目錄人員（PersonId）供用量歸屬與層級預算
• 可設定模型允許清單：預設跟隨組織，或再縮小為自訂子集（見 允許清單）
• 組織儲值餘額／組織預算經由 Workspace → Organization 解析

生命週期

1. 在 Admin「API Keys」頁（/app/{workspaceId}/keys）建立金鑰 → 複製明文
2. 放到客戶端環境變數（例如 HAKILA_API_KEY）
3. 每次請求帶 Authorization: Bearer ...
4. 輪替：建立新金鑰 → 切換客戶端 → 停用舊金鑰

安全建議

• 不要把金鑰提交到 Git 或前端公開 bundle
• 依環境（dev / staging / prod）分開金鑰
• 為自動化任務設定預算上限，避免異常用量

詳見 認證、模型允許清單 與 用量與預算。