透過表單申請特定的流程發動key與API語法，就能用熟悉的程式開發，甚至用PowerShell or BAT批次檔發動流程並把資料寫入平台(當然！建議用安全的方式保存API Key，此例只是呈現過程是如此簡單)

1. 什麼情況用這條路徑

平台有兩條拿到 API Key 的路徑。本篇講的是「員工自助申請、Key 歸屬個人、管理員只做核准」的申請單路徑；管理員直接配發的路徑在第 01 篇。

金鑰不經手任何人
核發節點產生 secret 後立刻丟棄明文，只留一張「一次性領取憑證」給歸屬人。管理員在整條流程裡看不到 secret，也沒有替他人領取的功能。

2. 前提：資安表單要先授權給你的角色

申請單上的「授權表單」清單不是全企業的表單，而是「Key 歸屬人自己填得到、而且已發行」的表單。規則是：你手動填得到的表單，才能申請一把 Key 去自動填。判定方式如下：

• 持有「流程設計師」或「表單設計師」角色的人，任何已發行表單都填得到（供試行設計稿）。
• 一般表單沒有設任何自訂規則時，預設「企業成員（EMPLOYEE）」角色可填；外部廠商帳號不適用預設規則。
• 資安案件分類的表單相反：沒有任何自訂規則時，誰都填不到、也申請不到。它們刻意不出現在表單中心「新填表單」區（改由資安案件處置中心呈現），但只要該表單的配對上授權了角色，持有那個角色的人就會在申請單的「授權表單」清單裡看到它。
• 代同事申請時，清單依「被代申請的那位」計算；換人時清單重新載入，對方填不到的已勾項目會被自動移除。外部廠商帳號不能代他人申請。

DemoSOC 出廠已把三張資安表單（SEC_INCIDENT_RESPONSE、SEC_IR_SOC_TEAM、SEC_IR_SOLO）授權給角色「資安人員（SECURITY_STAFF）」與「資安主管（SOC_SUPERVISOR）」。實跑時以 linda.hu@demo-soc.example（資安人員）查詢，清單共 6 張：

2.1 管理員要在哪裡授權

選單「表單流程 ／ 配對管理」（路徑 /forms/mappings），找到該表單那一列，按「權限」按鈕（按鈕上會顯示規則筆數，沒有規則時顯示「預設」），開啟「填寫權限設定 - 表單名稱」視窗：

資安表單的「預設規則」那三行不適用
視窗裡「未設任何自訂規則時企業成員可填」是一般表單的規則。資安案件分類的表單沒有自訂規則時是全部拒絕，所以要讓資安人員申請得到 Key，至少要加一條「角色」規則。

3. 填寫申請單

申請人登入後開「表單中心」，在「新填表單」區的分類「其他」找到卡片「API Key 申請單」，點卡片開啟「填寫表單 - API Key 申請單」視窗。視窗最上方是平台層的「表單主旨」（必填），下方才是申請單本身的欄位：

按「送出表單」。成功時畫面回「表單已送出，流程已啟動」，表單中心會出現這張單的序號（實跑為 Form-260900025）。

有效期限與其他必填欄位留空送不出去
「使用者（Key 歸屬人）」「授權表單」「用途說明」「有效期限」都是必填，送出前畫面會擋；就算繞過畫面直接送，伺服器也會回 400 missing_required_fields，訊息「缺少必填欄位：欄位名稱」。「用途說明」的 10 字下限由表單本身檢查。

來源 IP 限制填的是「設備的 IP」，不是你的工作機
這個限制會寫進 Key 的來源白名單，之後從白名單以外的主機打 API 一律 401。填了工作機 IP、再把 Key 放到設備上，設備就會被擋。實跑用鎖了 192.168.0.111 的 Key 從另一台主機呼叫，回應是 401 auth_failed。如果設備在 NAT 後面，要填 NAT 之後平台看到的 IP。

4. 管理員核准

出廠的「API Key 申請核發流程」只有一個人工關卡。流程如下：

4.1 管理員在哪裡看到申請單

企業管理員開「表單中心」，「待簽核」區會列出這張單：欄位為單號、表單（API Key 申請單）、主旨、發起人、類別、目前關卡（顯示「管理員核准」）、等待時間、操作。按該列的「簽核」按鈕（若別人正在簽會顯示「簽核中」且不能按），開啟「簽核表單」視窗：

• 視窗頂端顯示表單名稱、單號、「主旨：」、「申請人：」、「關卡：」、「簽核者」。
• 中段是申請單內容（歸屬人、授權表單、用途說明、有效期限、來源 IP 限制），這是核發前唯一的把關點，管理員在這裡看得到 Key 歸屬人與授權表單範圍。
• 「請選擇決策」區有兩顆按鈕：「核准並核發」與「駁回」。點選後下方顯示「已選擇：決策名稱」。沒選就按送出會提示「請選擇一個決策選項」。
• 「簽核意見」為選填（出廠設定不強制），可搭配簽核片語。
• 按「送出簽核」。實跑回應「簽核完成」。

4.2 核准之後系統做什麼

「核發 API Key」節點在核發前會再檢查一次，任一項不符就不核發，流程停在這個節點：

檢查通過後，系統建立 Key（名稱＝表單主旨、說明＝用途說明加一行「來源申請單: 申請單識別碼」、授權範圍＝勾選的表單模板、來源 IP 白名單＝「來源 IP 限制」拆成的清單、期限＝有效期限當天結束），並建立一張只有歸屬人能用的一次性領取憑證，有效 72 小時。Key 的 secret 明文在這一步就被丟棄，之後只能靠領取憑證解出一次。

接著「寫回核發結果」節點把下面這段文字寫進申請單的「核發結果」欄位（實跑值，識別碼即這把 Key 的 key_id）：

已核發 API Key，識別碼 ak_7bbdad985194ff13。請 Key 歸屬人本人登入平台，於「個人設定」頁一次性領取金鑰；金鑰只顯示一次，逾期未領取需重新申請。

實跑中核准後五個節點（Start、管理員核准、核發 API Key、寫回核發結果、End）全部 SUCCESS，流程狀態 COMPLETED。選「駁回」則直接到 End，不建立任何 Key，申請單與簽核記錄照常保留。

5. 本人領取金鑰

歸屬人登入後開「個人設定」（路徑 /personal-settings），頁面下方有「我的 API Key」區塊。沒有任何 Key 時顯示「目前沒有屬於你的 API Key。可到表單中心提出「API Key 申請單」。」有 Key 時是一張表格：

這張表只列「歸屬人是你」的 Key。別人替你申請的 Key 會出現在你的頁面、不會出現在申請人的頁面；管理員也沒有替你領取的功能。

在【個人設定】的最下面，要捲動

5.1 領取

按「領取金鑰」。系統確認這張領取憑證屬於你、尚未領取、還沒過期，而且 Key 仍是啟用狀態，然後把 secret 解出來顯示一次，並開啟「API Key 串接範例」視窗（內容見第 6 節），視窗頂端警示：

這串金鑰只會顯示這一次。關閉後將無法再次查看，遺失時只能重新產生。

底層 API 的回應（實跑值，secret 已隱去）：

POST /api/my-api-keys/<key 識別碼>/claim
{
  "success": true,
  "data": {
    "key_id": "ak_7bbdad985194ff13",
    "secret": "<領取時顯示一次的 secret>",
    "claimed_at": "2026-09-26T15:35:45"
  }
}

領取後表格的「金鑰」欄變成「已於 時間 領取」，按鈕變成「查看串接範例」與「重新產生金鑰」。

5.2 只能領一次、72 小時內要領

• 領取憑證在核發當下建立，72 小時後失效；表格「金鑰」欄的「領取期限」就是這個時間。
• 再按一次領取（或用工具重送）回 HTTP 400，訊息「這筆領取憑證已失效或已領取過」。實跑第二次呼叫：

{"success": false, "error": "這筆領取憑證已失效或已領取過"}   HTTP 400

• 憑證過期後「金鑰」欄顯示「領取期限已過」，「領取金鑰」按鈕消失。申請單「核發結果」寫的是「逾期未領取需重新申請」，不過此時頁面仍會出現「重新產生金鑰」按鈕（見 5.3），Key 本身還在、只是沒人拿到 secret；按下去就能拿到一組新的 secret，不必重新走一次申請流程。
• 領取失敗的原因（不是你的、已領過、過期、Key 已暫停或撤銷）一律回同一句「無法領取 API Key」，畫面不會告訴你是哪一種。

5.3 重新產生金鑰

按「重新產生金鑰」會先跳確認：「重新產生後，舊的金鑰立即失效，所有正在使用它的系統都會連不上。確定要繼續嗎？」確定後系統換一組 secret、開同一個「API Key 串接範例」視窗顯示一次。Key 必須是啟用中；已暫停的 Key 會回「已停用的 API Key 不可重新產生金鑰」；已撤銷的 Key 會直接從「我的 API Key」列表消失。

6. 查看串接範例

領取當下、重新產生當下，或之後按「查看串接範例」，都會開同一個「API Key 串接範例」視窗，內容由上到下：

以本篇的 Key、表單「資安事件處置」、預填值不動、事後開啟（金鑰以環境變數佔位）為例，視窗產生的 curl 是：

BASE='http://192.168.0.112:8000/beakplatform'
KEY_ID='ak_7bbdad985194ff13'
SECRET="$BP_API_KEY_SECRET"
BODY='{"form_code":"SEC_INCIDENT_RESPONSE","subject":"外部系統觸發","form_data":{"actor_ip":"203.0.113.42","finding_rule_id":"RULE-1","severity_id":"3","source_system":"manual"}}'
TS=$(date +%s)
KEY_HEX=$(printf '%s' "$SECRET" | tr '_-' '/+' | base64 -d | xxd -p | tr -d '\n')
SIG=$(printf '%s\n%s' "$TS" "$BODY" | openssl dgst -sha256 -mac HMAC -macopt hexkey:"$KEY_HEX" -hex | awk '{print $NF}')
curl -s -X POST "$BASE/api/trigger/form" \
  -H 'Content-Type: application/json' \
  -H "X-BP-Key-Id: $KEY_ID" \
  -H "X-BP-Timestamp: $TS" \
  -H "X-BP-Signature: sha256=$SIG" \
  -d "$BODY"

這幾行在做的事：

• SECRET：剛領到金鑰時這行是 SECRET='<真實 secret>'；事後開啟時改用雙引號包環境變數，執行前要先 export BP_API_KEY_SECRET='<當初保存的 secret>'。
• KEY_HEX：secret 是 base64url 字串，先換回標準 base64 字元、解碼成原始位元組，再轉成十六進位給 openssl 當 HMAC 金鑰。不要拿 secret 字串本身當金鑰，那樣簽出來的東西一律 401。
• SIG：對「時間戳、換行、body」這串文字算 HMAC-SHA256，時間戳是 Unix 秒，與平台時間差超過 5 分鐘也是 401。
• 三個 X-BP-* 標頭把 key_id、時間戳、簽章帶給平台；-d "$BODY" 送出的內容必須與簽章時的位元組完全一致，不要事後重排 JSON。

簽章規格的完整說明、用 <平台安裝目錄>/scripts/bp_trigger.py 免算簽章的做法、以及回應與錯誤碼，見第 03 篇。該篇的工具吃 BP_BASE_URL／BP_KEY_ID／BP_SECRET 三個環境變數，BP_SECRET 放的就是這裡領到的 secret。

7. 管理員端看到什麼

申請流程核發的 Key 與管理員直接建立的 Key 放在同一張表：「系統安全 ／ API Key 管理」（路徑 /security/api-keys/）。列表欄位為 Key ID、名稱 / 使用者、授權範圍、IP 鎖定、期限、最後使用、狀態、操作。本篇這把 Key 在列表上長這樣：

從管理 API 讀這筆記錄還能看到：applicant_user_secure_code＝歸屬人、created_by_secure_code＝wf: 加流程實例識別碼（表示由流程建立，不是某位管理員）、scopes＝{"form_template": [...]}、description＝用途說明加一行「來源申請單: …」。

管理員可以對它做的事與其他 Key 相同：「暫停」（可復原）、「復原」、「撤銷」（不可逆）、「編輯」（改名稱、期限、IP 白名單、追加分類或個別表單範圍）。不同的是：

• 「編輯」視窗會多一個區塊「授權範圍 - 表單模板（申請流程核發）」，說明「N 筆表單模板授權由 API Key 申請流程核發，此處不可編輯；儲存本表單時會原樣保留。」要縮小這把 Key 的範圍只能撤銷後請本人重新申請。
• 管理端沒有「領取金鑰」或「重新產生金鑰」；secret 從頭到尾只有歸屬人本人拿得到。
• 管理員暫停之後，本人頁面的「領取金鑰」會失敗（回「無法領取 API Key」），「重新產生金鑰」會回「已停用的 API Key 不可重新產生金鑰」；撤銷之後這把 Key 直接從本人的「我的 API Key」列表消失。

8. 注意事項

「授權表單」清單裡沒有資安表單
症狀：只看得到「其他」分類的表單，或清單顯示「沒有可申請的表單」。
原因：資安案件表單沒有規則時是全部拒絕，而且清單依「Key 歸屬人」而不是填單的人計算——代申請時對方沒有角色，你有也沒用。
做法：請管理員到「表單流程 ／ 配對管理」該表單的「權限」加一條角色規則（例如「資安人員」），並確認歸屬人真的持有該角色。

管理員核准了，但「我的 API Key」沒有出現新的一列
症狀：申請單的「核發結果」欄位空白，個人設定頁沒有這把 Key。
原因：「核發 API Key」節點在核准當下重算了一次歸屬人的填寫權限，最常見是核准前角色被拿掉、歸屬人被停用，或送單時塞進了歸屬人填不到的表單；節點回的錯誤訊息是第 4.2 節那張表其中一句，流程停在該節點。
做法：修正權限或帳號狀態後重新申請一張。

領取期限過了
「金鑰」欄變成「領取期限已過」，「領取金鑰」按鈕消失。Key 還在，按「重新產生金鑰」會立刻顯示一組新的 secret（只顯示一次）。管理員無法替你延長或代領。

「來源 IP 限制」填了工作機 IP，設備打 API 卻 401
白名單在驗章之前就檢查，只要來源不在清單內就是 401 auth_failed，回應不會說是 IP 的問題。從自己的工作機測試通了、搬到設備上就失敗，通常就是這個原因。請管理員在「API Key 管理」的「編輯」視窗改「來源 IP 白名單」，或重新申請時填設備的 IP；動態 IP 的設備建議留空。

「重新產生金鑰」會讓舊金鑰立即失效
確認對話框已經寫明：所有正在使用舊金鑰的系統都會連不上。先確定設備能同步更新設定再按；只是想「再看一次」金鑰是不行的，關閉視窗後沒有任何地方可以再看到舊值。

兩個容易混淆的時間
「有效期限」是 Key 本身的壽命（申請單上填的日期，用到當天結束）；「領取期限」是拿 secret 的時限（核發後 72 小時）。前者到期 Key 失效、要重新申請；後者到期只是還沒拿到 secret，用「重新產生金鑰」即可。

簽核記錄與決策
管理員選「駁回」時流程直接結束、不核發，申請人在表單中心看到的是這張單已結束而「核發結果」為空；要知道原因看簽核意見。

9. 下一步

拿到 key_id 與 secret 之後，到第 03 篇：從你的設備建立第一張資安案件，用 bp_trigger.py 或第 6 節那段 curl 打 POST /api/trigger/form，並對照 28 個資安表單欄位把設備的告警對應進去。