SCIM 自動佈建

SCIM（System for Cross-domain Identity Management）2.0 是同步使用者與群組的標準 REST API。啟用後，公司的身分提供者（IdP）會主動把員工與部門推送到 Hakila：新進、異動、停權都自動反映在組織的人員與單位上，不需要在 Console 手動維護。

同步方向是單向的：IdP 呼叫 Hakila，Hakila 不會反過來讀取 IdP。

同步的是什麼

組織結構的概念請見 Workspace，預算的檢查順序請見用量與預算。

啟用

只有組織管理員可以設定，且組織須為 Enterprise 方案（見組織方案）；Business 方案的組織呼叫 SCIM 端點一律回 401。

1. Console → 組織管理 → 組織人員管理 → 成員管理，在「SCIM 自動佈建」區塊按 啟用並產生 Token。
2. 複製畫面上的兩個值，貼到 IdP 的 SCIM 設定：
   • SCIM 端點（Tenant URL）：https://api.hakila.ai/scim/v2
   • Secret Token：hkscim_ 開頭的字串
3. 在 IdP 指派要同步的使用者與群組，開始佈建。

Token 只在產生當下顯示一次，Hakila 只保存它的雜湊值；遺失時請重新產生。

• 重新產生 Token：舊 Token 立即失效，需同步更新 IdP 的設定。
• 停用：Token 失效，IdP 無法再同步；已佈建的人員與單位會保留。

每個組織的 Token 各自獨立，Hakila 以 Token 判斷要寫入哪個組織。卡片上會顯示最近一次同步時間，以及已佈建的人員與單位數。

設定身分提供者

欄位對應

User

groups 為唯讀，顯示人員目前所屬的單位；調整隸屬請透過 Group 的 members。

Group

同步行為

新進人員。 IdP 建立 User 時，若組織內已有手動建立、尚未同步過的人員，且其 Email 與 userName 相同，Hakila 會直接接手這筆人員，保留原有的預算、流量限制與 API Key 綁定；否則建立新人員。導入 SCIM 前已手動建好的人員，只要 Email 一致就不會重複。

停權。 active 改為 false 後，指派給這位人員的 API Key 會立即無法呼叫，回傳 401。重新啟用後恢復。

刪除人員。 DELETE /Users/{id} 會刪除人員，效果與在 Console 刪除相同。多數 IdP 在取消指派時只會先停權（active = false），之後才刪除。

部門異動。 每位人員只隸屬一個單位：

• 把人員加入某個 Group，等於把他移到該單位；他已綁定的 API Key 也跟著改套用新單位的預算與限流。
• 從 Group 移除，人員會回到根組織。
• 同一人被加入多個已同步的 Group 時，以最後一次異動為準。建議只把代表部門的群組同步到 Hakila。

單位階層。 透過 SCIM 建立的單位一律放在第一層。需要上下層關係時，到「組織人員管理 → 組織階層管理」調整；之後 SCIM 更新同一單位不會改動它的上層。

刪除單位。 DELETE /Groups/{id} 只刪除該單位，底下的子單位與人員會移到上一層，不會一併刪除。這與在 Console 刪除單位不同（Console 會連同子單位與人員一起刪除）。

手動編輯。 SCIM 佈建的人員在 Console 仍可編輯，但姓名、Email、單位與啟用狀態可能在 IdP 下次同步時被覆寫，建議在 IdP 端調整。預算、流量限制與 API Key 綁定只在 Hakila 管理，不會被同步覆寫。

端點

所有端點都需要 Authorization: Bearer hkscim_…，回應的 Content-Type 為 application/scim+json。

分頁：startIndex 從 1 起算；count 預設 100，上限 1000。

Filter

只支援 eq 比較，可用 and 串接多個條件：

其他運算子（co、sw、or 等）回傳 400，scimType 為 invalidFilter。

PATCH

支援 add、replace、remove，path 可省略（以 value 物件一次更新多個屬性）。

• Users：active、userName、displayName、name（含 name.givenName 等子屬性）、emails、externalId。active 也接受字串 "True"／"False"。
• Groups：displayName、externalId、members。remove 可用 members[value eq "…"] 指定成員；不指定成員時移出全部。

範例

確認 Token 可用：

curl "https://api.hakila.ai/scim/v2/Users?count=1" \
  -H "Authorization: Bearer $HAKILA_SCIM_TOKEN"

停權一位人員：

curl -X PATCH "https://api.hakila.ai/scim/v2/Users/{id}" \
  -H "Authorization: Bearer $HAKILA_SCIM_TOKEN" \
  -H "Content-Type: application/scim+json" \
  -d '{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [{ "op": "replace", "path": "active", "value": false }]
  }'

把人員加入單位：

curl -X PATCH "https://api.hakila.ai/scim/v2/Groups/{groupId}" \
  -H "Authorization: Bearer $HAKILA_SCIM_TOKEN" \
  -H "Content-Type: application/scim+json" \
  -d '{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [{ "op": "add", "path": "members", "value": [{ "value": "{userId}" }] }]
  }'

錯誤

錯誤回應採 SCIM 格式：

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
  "status": "409",
  "detail": "userName alice@example.com 已存在",
  "scimType": "uniqueness"
}

相關頁面

• Workspace
• API Key 概念
• 用量與預算