API 金鑰管理

定義

API Key 的產生、儲存、配對、撤銷等生命週期管理。核心原則：Key 只顯示一次、儲存 Hash 而非明文、提供撤銷機制。

關鍵數據點（附來源）

• Key 產生時完整顯示一次，之後僅顯示遮罩版本（前 8 碼 + 後 4 碼），參考 GitHub PAT 做法。（api-security-design-connection-key）
• 後端只儲存 Key 的 Hash 值，不存明文。（api-security-design-connection-key）
• 儲存方式判準（重要）：只需要「驗證來的對不對」就存 Hash；需要「拿原文出來再用一次」就必須可逆加密。LINE 中繼站的 relay_secret 要對轉發出去的 Webhook 重新簽章，Hash 是單向的簽不回來，因此改用 AES-GCM 加密存。（line-login-relay-cloudflare-workers）
• 可逆加密時，解密鑰匙要與被加密資料分離存放：RELAY_ENC_KEY 只在 Workers 環境變數，不進資料庫。（line-login-relay-cloudflare-workers）
• 最高等級的憑證連加密存都不存：Channel Secret 只放環境變數，資料庫整個被撈走也換不到 token。（line-login-relay-cloudflare-workers）
• 「只回傳一次」的做法在多租戶場景同樣適用：site_key 只在站台登記那一刻回傳一次。（line-login-relay-cloudflare-workers）
• 提供「重新產生」（舊 Key 失效）和「撤銷」（切斷連線）兩種管理操作。（api-security-design-connection-key）
• Notion Integration Token、OpenClaw Bot Token 都是需要安全管理的 API Key。（github-actions-notion-commit-log、openclaw-telegram-setup）
• OpenClaw 的檔案權限建議收緊至 600/700，防止非 owner 讀取。（openclaw-telegram-setup）
• GitHub Secrets 是儲存 token 的安全方式。（github-actions-notion-commit-log）

儲存方式決策表

用途	儲存方式	理由
只需驗證來的 Key 對不對	存 Hash	單向即可，外洩後無法還原
需拿原文再簽章／再呼叫	可逆加密（如 AES-GCM），鑰匙分離存放	Hash 簽不回來
代表整個平台的主憑證	只放環境變數，不進資料庫	資料庫外洩不致全盤皆輸

前提與局限性

• Key 管理靠人：系統無法防止管理員將 Key 貼在公開頻道。「只回傳一次」降低的是後台反覆曝光的面積，不是解決人為外洩。
• Token 過期且無告警機制時，整合會靜默失敗。
• 單一 Key 無權限分級，持有者擁有完整存取權。

衝突標記

• 表面矛盾已釐清：本條目原主張「只存 Hash 不存明文」，而 line-login-relay-cloudflare-workers 使用 AES-GCM 可逆加密。兩者不牴觸，是適用條件不同，判準見上方決策表。不區分兩者會導致在需要重簽的場景錯用 Hash。

關聯概念

• [[請求簽章]]
• [[Zero Trust Access]]
• [[通訊平台 Bot 安全設計]]
• [[Notion API]]
• [[一對多信任邊界]]