Skip to Content
安全API 金鑰

API 金鑰

三種憑證，三種威脅模型。

pk_ — Publishable

  • 設計上就是要送到瀏覽器。每個已簽章的 B2B 請求都會以 X-Client-ID 標頭帶著它，也會內嵌在 SDK bundle 中，供 用戶端開啟結帳時使用。
  • 可以識別你的帳號；但無法建立 session、讀取其他商家的資料， 或觸發任何具破壞性的操作。
  • publishable key 外洩屬於低嚴重度事件。

sk_ — Secret（HMAC 簽章金鑰）

  • 所有 B2B API 呼叫用的 HMAC-SHA256 簽章金鑰 — 見 身分驗證。
  • 永遠不會在網路上傳輸。只有它衍生出的逐請求簽章會傳輸。所以 你只需要擔心儲存層的外洩（env var、git、log），不用擔心 傳輸層。
  • 僅限伺服端使用。不應該出現在瀏覽器 bundle、公開 repo、 截圖或聊天訊息中。
  • secret key 外洩屬於高嚴重度事件。

whsec_ — Webhook 簽章密鑰

  • 用來驗證我們對你伺服器所做的入站 webhook 投遞的簽章。見 簽章驗證。
  • 每個 webhook 端點各自獨立 — 若你註冊了 3 個端點，就會有 3 組 不同的 whsec_ 密鑰。環境編碼在前綴中：whsec_live_… / whsec_test_…。
  • 僅限伺服端使用。和 sk_ 一樣，永遠不會在網路上傳輸 — 只用來 在本地驗證 HMAC。
  • 輪替有 24 小時的寬限視窗。 點擊 Rotate 後，前一個密鑰在 24 小時內仍會被接受，與新密鑰並存（投遞會同時帶 X-Signature 與 X-Signature-Prev），讓你可以在不中斷流量 的情況下重新部署驗證器。
  • 顯示既有密鑰的功能是可用的，但需要新的 2FA 驗證並記錄在 稽核日誌中 — 適用於密鑰遺失、且無法接受輪替的情境。儀表板 的預設立場是「輪替，而非顯示」。
  • webhook 密鑰外洩，會讓攻擊者能對你的 URL 偽造事件。嚴重度為 中到高，取決於你對事件酬載的信任程度。

Scope

Secret key 是有範圍限定的。儀表板讓你可以用下列其中一種 scope 組合鑄造金鑰：

Scope可以做什麼用於
read列出 / 讀取訂單、session、退款、餘額唯讀整合（分析、BI）
write_order全部 read 權限 + 建立 session、建立訂單、取消訂單商店後端
write_refund全部 read 權限 + 建立退款、標記退款已執行客服工具
webhook_manage全部 read 權限 + 管理 webhook 端點DevOps 工具

預設鑄造的「full access」金鑰會擁有全部四種 scope。鑄造分用途的 金鑰仍然是良好的習慣 — 它能記錄意圖，也能在強制執行上線時讓你 提前準備好 — 但在把 scope 當成安全邊界之前，請先讀完下面的但書。

Scope 目前僅供參考 — gateway 尚未強制執行。 Gateway 會驗證 金鑰的 HMAC 簽章，並把你的商家身份（X-Merchant-ID / X-Merchant-Domain）注入下游服務，但不會傳遞或檢查金鑰的 scope。實務上這代表任一 scope 的 sk_ 外洩，都能呼叫你商家 底下任何 /b2b/v1/* endpoint — read 金鑰其實並沒有被 阻止建立退款。所以窄範圍的 scope目前並不能限制爆炸半徑： 在做外洩應變規劃時，請把每一把 secret key 都當成 full-access 處理，並仰賴快速輪替 + 撤銷（見下文）作為真正的圍堵手段。 逐 scope 的強制執行在路線圖上。

輪替

  1. 產生新金鑰。 儀表板 → Developers → API keys → + Add key。選擇 scope。儀表板只會顯示一次密鑰 — 請立刻 儲存下來。
  2. 把 env var 換成新值，套用到所有環境。部署。
  3. 驗證流量。 儀表板會即時顯示逐金鑰的請求數。等舊金鑰的 請求數降到零。
  4. 撤銷舊金鑰。 同一畫面 → ⋮ 選單 → Revoke。

目前沒有自動的重疊視窗 — 一旦你撤銷金鑰，任何用它簽章、 仍在傳輸中的請求都會收到 401。請據此規劃你的輪替流程：先 部署新金鑰，等舊金鑰的流量退乾，再撤銷。

緊急撤銷

若金鑰已經外洩（出現在 git 歷史、公開的 bundle、被記錄下來的 stack trace，或合作夥伴的滲透測試報告中）— 請立刻撤銷，即使 會導致部分請求失敗也一樣。與其讓攻擊者持有有效憑證，不如讓 系統明顯地失敗。

步驟：

  1. 儀表板 → Developers → API keys → [金鑰] → Revoke now。 效果是立即生效的；沒有寬限期。
  2. 鑄造一把替代金鑰並部署。
  3. 稽核近期活動 — 儀表板會顯示每把金鑰最近 30 天的請求紀錄， 含 IP 與命中的 endpoint。

若你懷疑外洩範圍不只一把金鑰，請聯絡 [email protected] 以：

  • 取得你商家帳號完整的稽核日誌匯出
  • 批次輪替 webhook 密鑰
  • 視需要在調查期間凍結帳號

儲存最佳實務

  • 只用 env var。 絕不把密鑰提交進 git，即使是寫著 「REPLACE ME」的 .env.example 也一樣。
  • 依環境分金鑰。 開發 / staging / production 各自使用不同 的 sk_test_… 與 sk_live_…，並從你的密鑰管理工具取得 （AWS Secrets Manager、Vault、Doppler……）。
  • 限制 env var 的存取權。 在 Kubernetes 中，請掛載為 Secret，而不是 ConfigMap。在 Vercel / Netlify 中，請使用 環境變數層級的範圍限定，而非專案層級的全域變數。
  • 不要記錄帶有 body 的請求。 即使是在除錯時也一樣 — 你在 X-Signature 中的 HMAC 簽章雖然是單次使用的，但你的業務 酬載可能含有個資。

目前不支援的功能

  • ❌ secret key 的 IP 允許清單。在路線圖上。
  • ❌ OAuth 風格的逐使用者範圍 token。 目前的金鑰模型是 逐商家、而非逐使用者。
  • ❌ 自動金鑰輪替（例如平台強制的每週輪替）。目前是手動的。

下一步

簽章驗證更新紀錄