API是從BeakPlatform外部發動流程的唯一方式，有兩種建立API的方式，今天先介紹讓企業管理員建立的方式，但是管理員太累了，而且放著流程自動化工具不用太浪費，可以透過表單系統配發，而且還能留下稽核記錄，下篇說明

1. 什麼情況用這條路徑

平台有兩條拿到 API Key 的路徑。本篇是企業管理員直接配發：管理員在「系統安全 ／ API Key 管理」替一台設備建立 Key，當場拿到 secret，再交給設備。另一條是第 02 篇的表單中心申請單：員工自己填「API Key 申請單」，管理員核准後由系統核發，歸屬人本人到個人設定領取。

設備符合以下任一情況，用本篇這條：

• 設備不屬於某個員工（WAF、防火牆、掃描器、排程主機），沒有「歸屬人」可以去領金鑰。
• 要把設備建出來的案件掛在一個專用帳號名下，讓簽核鏈上的「申請人」有明確身分。
• 要鎖定來源 IP，而且日後可能還要調整白名單。

2. 建立 API Key

2.1 選單位置

以企業管理員登入後，左側選單「系統安全 ／ API Key 管理」，網址是 http://192.168.0.112:8000/beakplatform/security/api-keys/ 。頁面上方的說明是「外部系統以 HMAC 簽章發動表單流程的專屬金鑰。每個外部系統/裝置一把 Key，來源清楚可稽核。」——一台設備一把 Key，不要多台共用。

找不到「系統安全」這個群組，代表目前登入的帳號不是企業管理員；請換帳號，不要用系統管理員或一般員工帳號嘗試。

2.2 「建立 API Key」視窗的欄位

按右上角的「建立 API Key」按鈕。視窗欄位如下，欄位名稱與畫面一致：

底部按鈕：「取消」、「建立」。

2.3 授權範圍怎麼選

三個授權範圍欄位可以並用，任一個涵蓋到目標表單即可建單。本系列的設備只走 POST /api/trigger/form，所以：

• 勾「資安案件」分類。示範企業 DemoSOC 出廠的三張資安表單（「資安事件處置」、「資安事件處置（SOC 團隊版）」、「資安事件處置（小企業單人版）」）都在這個分類下，勾一次全部涵蓋。
• 只想讓設備建其中一張時，改在「個別表單（例外直綁）」勾那一張，分類留空。
• 「資安事件接收（OpenDefense intake，選填）」留空。它是給會送 OCSF／原生 payload 到 /api/open_defense/intake 的整合型防禦節點用的，走的是「事件路由設定」那套規則，不是本系列講的表單觸發路徑。填了不會讓 /api/trigger/form 多出任何權限。

授權範圍只決定「能建哪張表單」，不決定欄位
設備送進來的欄位必須是那張表單的欄位，欄位名對照在第 03 篇。這裡只要確定表單在範圍內就好。

2.4 本篇範例：WAF-01

按「建立」，成功後視窗關閉並跳出「API Key 已建立」視窗，進入第 3 節。

3. 保存 secret

3.1 「API Key 已建立」視窗

視窗最上方是紅色提示：「Secret 僅顯示這一次，關閉後無法再查看。請立即複製並安全交付給外部系統。」接著是兩行：

key_id: ak_a85efc52cc2455a4
secret: <領取時顯示一次的 secret>

下方一行小字是簽章方式：「簽章方式：HMAC-SHA256(secret, "{timestamp}\n{body}")，headers：X-BP-Key-Id / X-BP-Timestamp / X-BP-Signature。工具與範例：scripts/bp_trigger.py、docs/install/api_trigger.md。」這行是給要自己實作簽章的人看的，第 03 篇會逐項說明；現在只要把兩個值存好。

按鈕「複製」會把上面兩行（含 key_id:／secret: 前綴）放進剪貼簿，成功後按鈕文字變成「已複製」；按「我已保存，關閉」視窗就關閉，secret 隨即從畫面與記憶體丟棄，列表與任何查詢都不會再回傳它。

關閉視窗前先把 secret 存到設備的設定檔或密碼庫
管理端沒有「重新顯示」也沒有「重發」。關掉之後才發現沒存到，唯一的做法是「撤銷」這把 Key 再建一把新的（第 4 節）。第 02 篇透過申請單核發的個人 Key 才有「重新產生金鑰」按鈕，本篇這條路徑沒有。

3.2 secret 長什麼樣、怎麼用

• key_id 固定是 ak_ 加 16 個十六進位字元，是公開識別碼，會出現在列表與平台日誌裡，不是秘密。
• secret 是 32 個隨機位元組經 base64url 編碼的字串（44 個字元，結尾通常是 =）。原樣保存、原樣使用，不要自行去掉 =、不要再做一次 base64、不要轉成十六進位。平台提供的 bp_trigger.py 會自己把它解碼回位元組再算 HMAC；自己實作簽章時也要先解碼（第 03 篇）。

建議把三個值放進設備或工作機的環境變數，bp_trigger.py 就認這三個名字：

export BP_BASE_URL='http://192.168.0.112:8000/beakplatform'
export BP_KEY_ID='ak_a85efc52cc2455a4'
export BP_SECRET='<領取時顯示一次的 secret>'

3.3 立刻驗證這把 Key 能用

bp_trigger.py 在平台安裝目錄的 scripts/ 底下，只用 Python 3 標準函式庫，複製到任何有 python3 的主機都能跑。先列出這把 Key 能建的表單：

python3 <平台安裝目錄>/scripts/bp_trigger.py --list

成功時第一行是「列出可發動表單成功（HTTP 200）」，接著是 JSON；以 2.4 的設定，data 陣列會有三筆，form_code 分別是 SEC_INCIDENT_RESPONSE、SEC_IR_SOC_TEAM、SEC_IR_SOLO，每筆的 field_keys 就是可送的欄位名。回到「API Key 管理」重新整理，這把 Key 的「最後使用」欄會從 - 變成時間。

如果回的是「列出可發動表單失敗（HTTP 401）」與 {"error": "auth_failed"}，先看第 6 節的排除順序。

3.4 系統實際存下的內容

建立成功時系統回傳的紀錄長這樣（畫面只顯示其中 key_id 與 secret；識別碼欄位以佔位表示）：

{
  "key_id": "ak_a85efc52cc2455a4",
  "name": "WAF-01 事件通報",
  "consumer_label": "WAF-01 (192.168.0.111)",
  "description": "WAF 事件自動建案",
  "scopes": {"form_category": ["<資安案件分類的識別碼>"], "form": []},
  "allowed_ips": null,
  "applicant_user_secure_code": null,
  "expires_at": null,
  "status": "active",
  "last_used_at": null,
  "secret": "<領取時顯示一次的 secret>"
}

scopes 就是三個授權範圍欄位的儲存形式：form_category（分類）、form（個別表單）、od_intake.source_systems（資安事件接收，沒填就不會出現這個 key）。allowed_ips 留空存成 null，代表不鎖。

4. 列表與日常管理

4.1 列表欄位

列表只有本企業的 Key，依建立時間新的在前。

4.2 四個操作

4.3 「最後使用」代表什麼

設備每一次通過驗章（headers、時間戳、Key 狀態、來源 IP、簽章五關全過），平台就把這把 Key 的「最後使用」更新為當下時間，然後才處理請求內容。所以：

• 有時間＝設備的憑證與網路路徑是通的，這是接線時最好用的檢查點。
• 有時間不代表案件建成功。欄位名打錯（400）、表單不在範圍（404）都會先更新「最後使用」才回錯誤。建沒建成要看設備收到的回應，或到「開放防禦 ／ 資安案件處置中心」找案件（第 03 篇）。
• 401 的呼叫不會更新它。設備一直打卻始終是 -，就是卡在驗章，看第 5、6 節。

5. 來源 IP 白名單怎麼判

5.1 格式

• 一行一筆。單一位址寫 192.168.0.111；網段寫 CIDR，例如 10.0.0.0/24。CIDR 的主機位元不必歸零，10.0.0.5/24 會被視為 10.0.0.0/24。
• 任何一筆格式不合法，整個建立或儲存都會被拒絕，訊息「IP 或 CIDR 格式錯誤: 」加上那一筆。
• 留空或全部刪掉＝不鎖，任何來源都可用（其他四關仍要過）。

5.2 比對的是哪個 IP

平台比對的是它看到的連線來源位址。設備經過 NAT、代理或 VPN 出口才連到平台時，平台看到的是轉換後的位址，白名單要填那個，不是設備自己網卡上的 IP。不確定設備出口是什麼，就先留空，用第 3.3 節的 --list 打通後，再從平台端的應用程式日誌看這把 Key 被記錄的 ip= 是多少，填上去。

設備是動態 IP 時不要鎖：畫面提示的做法是留空，遇到異常改用「暫停」處置。

5.3 驗章順序：白名單只是第四關

五關任一失敗，設備收到的都是同一個回應：HTTP 401、{"error": "auth_failed"}。平台刻意不告訴呼叫端是哪一關失敗，避免被拿來探測；真正的原因只記在平台端的應用程式日誌。所以來源 IP 被擋時，設備端看起來跟 secret 錯誤一模一樣。

實際例子：一把來源 IP 白名單設為 192.168.0.111 的 Key，從另一台主機執行 --list，得到的是：

列出可發動表單失敗（HTTP 401）
{
  "error": "auth_failed"
}

6. 注意事項

回 401 卻不知道為什麼
症狀：設備或 --list 一律得到 HTTP 401 auth_failed，「最後使用」始終是 -。　
原因：驗章五關之一沒過，回應不會說是哪一關。　
做法：照驗章順序逐項排除，每一步都排除了再看下一步：
1.header 齊不齊：自己實作時確認 X-BP-Key-Id、X-BP-Timestamp、X-BP-Signature 三個都有送，任一個空白直接 401。用 bp_trigger.py 可略過這一步。
2.時鐘：設備與平台的時間差必須在 300 秒內。在設備上跑 date -u +%s，和平台主機比一下；設備沒對 NTP 是最常見的原因。
3.Key 狀態：到列表看這把 Key 的「狀態」是不是「啟用中」、「期限」有沒有過；已撤銷的 Key 不會在列表上，找不到就是被撤銷了。
4.來源 IP：「IP 鎖定」欄有值時，確認平台看到的來源位址在白名單內（第 5.2 節）。要快速切割，先「編輯」把白名單清空試一次。
5.secret 與簽章：確認 BP_KEY_ID 對到列表上的 Key ID、BP_SECRET 是建立時原樣複製（沒有多空白、沒有少 =）。自行實作簽章時先拿 bp_trigger.py 用同一組憑證打一次，能過就是簽章實作的問題，不是憑證的問題。
另外，同一個來源位址一分鐘內累積 30 次 401 之後，平台會改回 HTTP 429（{"success": false, "error": "請求頻率過高，請稍後再試"}）。排錯時不要讓設備在迴圈裡重試，先停下來，一分鐘後再試。

「使用期限」填的那一天一開始就失效，不是那天結束
症狀：期限填 3 月 31 日，31 日早上設備就開始 401。　
原因：管理端把日期存成該日 00:00（UTC），平台以 UTC 判斷是否過期，換算成台灣時間是當天早上 8 點。　> 做法：期限填「最後可用日的隔一天」；或到期前一天先「編輯」延長。留空則永久有效。

分類勾了，設備卻建不了那張表單
症狀：回 HTTP 422 form_not_published（訊息「表單尚未發行」或「表單已有發行記錄，但目前沒有 Published 版本」），或 HTTP 404 form_not_found。　
原因：授權範圍只涵蓋已發行的表單。表單在範圍內但沒有發行中的版本是 422；form_code 打錯、表單不在這把 Key 的範圍內、表單不屬於本企業，都是 404，平台刻意不區分「不存在」與「沒授權」。　
做法：先用 --list 看這把 Key 目前能建哪些 form_code；沒列出來就去「表單管理 ／ 表單流程配對」確認該表單已發行，或回「編輯」補授權。

綁定專用帳號後，案件的申請人就是那個帳號
設備建出的案件在表單中心、待簽核清單與案件內容的「申請人」欄位顯示的是：有綁定申請人時，顯示該帳號的顯示名稱；沒綁定時，顯示「使用者標籤」；連標籤也沒填，就顯示 Key 的「名稱」。綁定的帳號之後被停用或刪除，設備的呼叫會回 HTTP 422 applicant_invalid（訊息「API Key 綁定的系統帳號不存在或已停用」）——這不是 401，看到它就直接去「編輯」換綁或改成不綁定。

「綁定申請人」下拉找不到想綁的帳號
下拉只列本企業「啟用中的一般員工」帳號，企業管理員與外部帳號不會出現；而且最多列 100 位（依建立時間新的在前）。要替設備綁專用帳號，先在帳號管理建一個一般員工帳號再回來綁。

「最後使用」有值不等於建單成功
它在驗章通過的那一刻就更新，之後的 400（欄位名錯）、404（表單不在範圍）、422 都不會把它清掉。確認案件有沒有建起來，看設備收到的回應，或到「開放防禦 ／ 資安案件處置中心」找案件編號（第 03 篇）。

7. 下一步
   你現在手上有 BP_BASE_URL、BP_KEY_ID、BP_SECRET，而且 --list 已經回 200。接著到第 03 篇 從你的設備建立第一張資安案件：對照表單欄位、用 bp_trigger.py 送出第一筆事件、到處置中心找到那張案件。

如果設備其實是某位員工在維護、Key 該歸屬那個人，改走第 03 篇 透過表單中心申請 API Key。