成員開通：SCIM／邀請／SSO

讓您的人員成為 MaiAgent 組織成員的三條路：SCIM 開通 API（適合客戶 IT 與 ISV 代管）、後台邀請、SSO 登入自動開通；以及與 MaiGPT 成員身分嵌入的銜接

MaiAgent 的「成員」是組織內有帳號的人（員工、承辦人），對應角色權限、Credits 額度與 MaiGPT 使用權；這和 Web Chat 的「聯絡人」（您的客戶、會員、匿名訪客）是兩套身分。本頁講的是成員怎麼開通，適合兩種對象：

• 客戶自己的 IT：要把公司員工批次建進 MaiAgent、離職時自動停用

• ISV／系統整合商：代管客戶組織，要用程式把客戶的人員開通進去，再用成員身分嵌入把 MaiGPT 嵌進自家系統

聯絡人（客戶端使用者）的建立與同步不在本頁，見軟體廠商整合指南。

目標是「把 MaiGPT 加進我們的系統」的話，先讀把 MaiGPT 加進您的系統，它把開通、換發、嵌入串成一條線；本頁是開通成員的完整參考。

名詞對照：SCIM 的 Group、IdP 的群組，在 MaiAgent 後台都叫「角色」——決定成員能用哪些 AI Agent、知識庫，以及 MaiGPT 的模型、工具、連接器。本頁在 API 語境用「群組」、後台語境用「角色」，指的是同一個東西。

一、三條路怎麼選

方式	適合	開通時機	離職／停用	人員怎麼登入 MaiAgent
SCIM 開通 API（本頁重點）	要用程式或 IdP 自動化；ISV 代管。沒有 IdP 也能用：事件即時同步或名單同步工具	您的系統或 IdP 主動推送	推送 active: false 即停用	需搭配 SSO（SCIM 建的帳號沒有密碼）；只做成員身分嵌入的話不需要登入
後台邀請（Email 邀請／組織邀請連結）	幾十人以內、不想串接	管理員在後台操作，對方收信或點連結	管理員在後台停用	Email 設定密碼登入，或 SSO
SSO 登入自動開通	員工本來就會登入 MaiAgent 網頁或 App	第一次用 SSO 登入時自動建立成員	依 IdP 是否放行登入；已建成員需另行停用	Keycloak／SAML／EIP／Cloudflare Access

三條路可以並用：常見組合是 SCIM 管名單＋SSO 管登入，或 SCIM 管名單＋成員身分嵌入（員工完全不登入 MaiAgent）。

成員數會影響方案裡的內建 Agent 席次與每成員 Credits 額度配置，批次開通前請先確認組織方案容量；額度設定見使用者手冊成員 Credits 額度管理。

二、SCIM 開通 API

MaiAgent 對每個組織提供 SCIM 2.0 的 inbound 端點（身分同步為企業版功能，方案內含與否請洽業務）。它只是標準 REST：既可以把 Endpoint 與 Token 填進 Okta、Microsoft Entra ID、JumpCloud 等 IdP 讓它們自動推送，也可以由您自己的後端直接呼叫。

整合前檢查清單

項目	說明
組織方案含身分同步	企業版功能，不確定請洽業務
組織 ID 與 SCIM Token	後台「身份同步 → SCIM → 連線資訊」，Token 只顯示一次
角色先建好、權限先設好	SCIM 建的成員不會進預設角色，SCIM 自動建立的角色權限是空的——成員建好卻什麼都不能用，九成是這個。建議先在後台建好角色（例如「客服」「主管」）並設定權限，含 MaiGPT 使用權，SCIM 再用相同名稱指派
方案容量	內建 Agent 席次與每成員 Credits 額度
先試少量	先建三五個人，到後台確認姓名、角色、能否開 MaiGPT，再全量
登入方式	只做成員身分嵌入可略；員工要登入 MaiAgent 就要 SSO

既有帳號與成員會怎樣

組織裡已經有人用 Email＋密碼、後台邀請或 SSO 在使用 MaiAgent 時，啟用 SCIM 不會讓他們原本的帳號失效：

常見疑問	實際行為
原本的帳號密碼還能登入嗎？	可以。只有 SCIM 新建的帳號沒有密碼；既有帳號的密碼、SSO 綁定都不會被動到
啟用 SCIM 會改變登入方式嗎？	不會。「身份同步」只決定 SCIM 端點能否使用；登入方式在「認證設定」另外管理
會不會多出一個重複帳號？	不會。帳號以 Email 為鍵：該 Email 已是本組織成員時，POST /Users 回 409 並附上既有成員的 id；是別的組織的帳號時，直接把同一個帳號加入本組織
沒被 SCIM 管到的舊成員會被停用嗎？	不會。SCIM 只會停用被明確送 active: false 或 DELETE 的成員；本站的名單同步工具也只停用自己管理（有 externalId）的成員
對話紀錄、額度紀錄會不見嗎？	不會。接管與停用都不會刪除成員資料；停用時只有該成員的 API Key 會立即撤銷

會改變的只有「被 SCIM 接管」的成員：IdP 或您的程式用 Email 查到既有成員並更新它之後，這個人就由 SCIM 管理——

• 顯示名稱會被 IdP／名單上的值覆寫；顯示名稱是帳號層級，這個人若同時在別的組織，那邊看到的名字也會跟著改

• 經 SCIM 指派的角色，以之後每次推送的 groups[] 為準；後台手動加的角色保留

• 在 IdP 或名單上停用、移除他，MaiAgent 這邊就跟著停用；即使他原本用密碼登入，停用後在本組織也一樣不能用

用 Okta、Entra ID 等 IdP 推送前，先確認 IdP 指派的人員範圍：範圍內的既有成員會被接管，之後停權、改名都聽 IdP 的。建議先指派三五個人（含一位既有成員）試跑，到後台確認姓名、角色與登入都正常，再擴大範圍。

啟用與取得 Token

1. 以組織擁有者登入後台，進入「組織設定 → 身份同步」，同步方式選擇 SCIM。只有擁有者能切換同步方式與重新產生 Token；角色具「身分同步權限」的成員只能檢視，後台操作見使用者手冊選擇 SCIM 時的後台操作

2. 「連線資訊」分頁顯示 Endpoint URL（形如 https://api.maiagent.ai/api/v1/scim/<組織 ID>）與 Token；點「重新產生 Token」取得新 Token

3. Token 只顯示一次，請立即存進您的伺服器密鑰管理；重新產生後舊 Token 立即失效；建立超過 180 天後台會提醒輪換

所有請求都帶：

Authorization: Bearer <SCIM Token>
Content-Type: application/scim+json

每個組織每分鐘 100 次請求的限流；超過回 429。

端點

方法	路徑（接在 Endpoint URL 之後）	用途
GET	/ServiceProviderConfig、/Schemas、/ResourceTypes	IdP 探索用
GET	/Users?filter=…&startIndex=1&count=50	列出／查詢成員
POST	/Users	建立成員
GET／PUT／PATCH	/Users/{id}	讀取／更新資源／局部更新（停用、改名、改 externalId）
DELETE	/Users/{id}	停用成員（見下方語意）
GET／POST	/Groups	列出／建立群組（對應 MaiAgent 角色）
GET／PUT／PATCH／DELETE	/Groups/{id}	群組改名、增減成員、刪除

filter 支援 userName eq "…"、externalId eq "…"、emails.value eq "…"（不分大小寫的等於比對）；Groups 支援 displayName eq "…"、externalId eq "…"。分頁用 SCIM 標準的 startIndex（從 1 起算）與 count。

User 資源欄位

SCIM 欄位	對應	說明
userName	帳號 Email	必填，就是 MaiAgent 的登入帳號；也是成員身分嵌入換發 token 時用的 email。建立後不可經 SCIM 變更（見生命週期）
emails[primary].value	帳號 Email	有給時優先於 userName
externalId	您系統的人員 ID	建議填，之後可用 filter=externalId eq "…" 反查
name.givenName／name.familyName／displayName	顯示名稱
active	成員啟用狀態	預設 true；false 即停用
groups[].display	加入的群組名稱	只對應已存在的群組（先 POST /Groups），見群組與角色

回應會多一個 id（MaiAgent 成員 ID，也就是換發 token 可用的 memberId）與 meta。

生命週期語意

• 建立：POST /Users 以 Email 為鍵。被管理員從組織移除的人員不會因 IdP 重送而自動恢復，建立請求回 403；需要先由管理員重新邀請。Email 在 MaiAgent 已有帳號（例如同一個人在別的組織）時直接加入本組織，不會另建帳號；同組織已有此成員回 409。新建的帳號沒有密碼，要登入 MaiAgent 網頁只能走 SSO；只做成員身分嵌入的人員不需要登入。

• 停用：PATCH 把 active 設為 false，或 DELETE /Users/{id}。兩者都是停用而非刪除：成員的對話、額度紀錄保留，該成員的 API Key 立即撤銷、角色權限隨之失效，之後換發成員 token 會回 404；重新啟用後角色恢復。組織只剩一位擁有者時，該擁有者不會被 SCIM 停用。

• 重新啟用：對既有成員 ID 使用 PATCH /Users/{id}，把 active 設回 true。停用不會刪除成員，因此對同一 Email 再 POST /Users 仍會回 409，不會重新啟用；可使用回應的 id 接續更新。

• 改 Email：不可經 SCIM 變更——PUT／PATCH 帶不同的 userName 會被忽略（帳號以 Email 為跨組織的鍵）。需要換 Email 時由管理員在後台修改，或停用舊成員、以新 Email 建立新成員（對話歷史不延續）。

• 更新：只改啟用狀態等個別欄位時請用 PATCH；PUT 解析時，未送 displayName、externalId 會使用空字串預設值，未送 active 使用 true；因此可能覆寫既有姓名、externalId 或重新啟用成員。未送 groups 則保留既有群組指派。PATCH 接受 {"Operations":[{"op":"replace","path":"active","value":false}]} 與 {"op":"replace","value":{"active":false}} 兩種寫法（Okta 與 Entra 各用一種）。

群組與角色

SCIM 的 Group 對應 MaiAgent 的角色（決定成員能用哪些 AI Agent、知識庫，以及 MaiGPT 的模型、工具、連接器）。三件事一定要知道：

1. SCIM 建的成員不會自動進「預設角色」，只會進 groups[] 指定的角色；沒指定就什麼權限都沒有。

2. SCIM 自動建立的角色權限是空的（POST /Groups 建的角色只有名字）。要讓成員能用 MaiGPT，得到後台角色權限把 MaiGPT 使用權打開，設定見MaiGPT 角色使用權限。建議做法：先在後台建好角色、設好權限，SCIM 用相同名稱指派。

3. User 的 groups[].display 只對應到「已與 SCIM 建立對應」的角色。對應在 POST／PATCH /Groups 時自動建立（預設開啟「自動建立角色」）；後台先建好的角色第一次由 SCIM 使用時，對它 PATCH /Groups/{id} 一次同名的 displayName 即可建立對應（本站的名單同步工具與即時同步 client 都已內建這一步），IdP 情境則在後台「群組映射」分頁指定 IdP 群組對應哪個角色。

其他行為：

• PATCH /Groups/{id} 支援 add／remove 個別成員，以及 replace 整份成員清單

• 同一成員經 SCIM 指派的角色，會被下一次 PUT／PATCH User 的 groups[] 整份取代；後台手動加的角色不受影響

• 刪除 Group 只解除成員與角色的關聯，不影響成員本身

範例

建立成員並加入「客服」群組：

curl -X POST "https://api.maiagent.ai/api/v1/scim/<組織 ID>/Users" \
  -H "Authorization: Bearer <SCIM Token>" \
  -H "Content-Type: application/scim+json" \
  -d '{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "userName": "[e-mail]",
    "externalId": "emp-10023",
    "name": { "givenName": "Alice", "familyName": "Chen" },
    "displayName": "Alice Chen",
    "active": true,
    "groups": [{ "display": "客服" }]
  }'

離職停用：

curl -X PATCH "https://api.maiagent.ai/api/v1/scim/<組織 ID>/Users/<成員 ID>" \
  -H "Authorization: Bearer <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}]}'

用您系統的人員 ID 反查成員：

curl "https://api.maiagent.ai/api/v1/scim/<組織 ID>/Users?filter=externalId%20eq%20%22emp-10023%22" \
  -H "Authorization: Bearer <SCIM Token>"

兩種不需要 IdP 的接法

您的情況	用哪一頁
您的產品是 Web 服務、有自己的使用者管理	即時同步：在使用者事件中呼叫——新增／修改／停用的當下呼叫，成員即時一致
人員名單在 HR 系統、Excel、資料庫	名單同步工具：CSV／JSON／資料庫——排程跑，名單有的建、沒的停

兩者可以並用：事件即時同步為主，名單工具每天對帳一次當保險。

從 IdP 推送

客戶若有 Okta、Microsoft Entra ID、JumpCloud 等 IdP，把 Endpoint URL 與 Token 填進 IdP 的 SCIM provisioning 設定即可，IdP 會自動推送使用者與群組、離職自動停用；同時在「認證設定」把同一個 IdP 設成 SSO（Keycloak 或 SAML），員工就能直接登入。SAML 設定見SAML SSO 單一登入整合。

三、後台邀請

不串接時由管理員在後台「組織設定 → 成員管理」操作：

• Email 邀請：輸入名單（一次最多 100 個），對方收信設定密碼即成為成員

• 組織邀請連結：把連結公告給員工自助加入

操作見使用者手冊成員管理。

四、SSO 登入自動開通

員工要自己登入 MaiAgent 網頁、MaiGPT 網頁版或 App 時，設定 SSO 讓他們用公司帳號登入：

方式	第一次登入時
Keycloak、EIP、SAML（含 ADFS）	自動建立帳號（或連結同一個 Email 的既有帳號），並加入設定此認證來源的組織
Cloudflare Access	依認證來源的「自動開通成員」開關決定；關閉時只放行已存在的成員

自動開通不會恢復被管理員移除、且尚未重新邀請的成員資格。EIP 在登入同時同步角色時會拒絕登入；Cloudflare Access 即使開啟「自動開通成員」，也會拒絕重新加入；SAML／Keycloak 不會把此人自動加回認證來源的組織，這不代表一律拒絕登入其他組織。需要恢復時，請先由管理員重新邀請成員，再使用原有登入方式。

這與目錄同步的「停用」不同：SCIM 停用後仍使用原有成員 ID 重新啟用，不要把重送建立請求當成恢復方式。從未加入組織的新成員仍依上表的自動開通規則處理。

設定方式見使用者手冊第三方登入（SSO）與技術文件SAML SSO 單一登入整合。SSO 只在登入時開通，離職者請用 SCIM 或後台停用，不要只依賴 IdP 拒絕登入：IdP 拒絕登入只擋下 SSO，帳號原本有密碼時仍可用密碼登入，該成員的 API Key 也仍然有效。後台操作見使用者手冊離職與停用成員。

五、與 MaiGPT 成員身分嵌入的銜接

ISV 代管客戶、要把 MaiGPT 嵌進自家系統時，兩支 API 的接法：

1. 客戶開通時，用 SCIM POST /Users 建成員（userName 填員工 Email、externalId 填您系統的人員 ID），並加入具 MaiGPT 使用權的群組

2. 員工開啟您的頁面時，後端以組織 API Key 呼叫成員 token 換發，email 就填同一個 Email（或 memberId 填 SCIM 回的 id）

3. 員工離職時 SCIM 停用，之後換發回 404，嵌入頁自然失效

員工全程不需要登入 MaiAgent，因此不需要設定 SSO；要同時開放 MaiGPT 網頁版或 App 再加 SSO。

六、常見問題

接了 SCIM 之後，原本的帳號還能用嗎？

可以。啟用 SCIM 不會改變既有成員的密碼、SSO 或登入方式，也不會建立重複帳號、不會停用沒被 SCIM 管到的人。唯一的變化是：被 IdP 或您的程式接管的既有成員，之後姓名、SCIM 角色與停用狀態會跟著來源同步。完整說明見既有帳號與成員會怎樣。

可以用「組織成員 API」直接建成員嗎？

後台的成員 API 是給管理介面用的，目前不提供給整合方；程式化開通請走 SCIM。

成員建好了，但登入後什麼都不能用／MaiGPT 打不開？

成員的能力全部來自角色。SCIM 建的成員不會進預設角色，SCIM 自動建立的角色權限又是空的，所以「建好了但什麼都沒有」是正常結果。到後台角色權限把該角色的權限（含 MaiGPT 使用權）設定好即可，或一開始就先建好角色再用 SCIM 指派。

SCIM 建的成員收得到邀請信嗎？

不會寄信。SCIM 是靜默開通：帳號沒有密碼、沒有通知；要讓員工登入請搭配 SSO，或改用後台 Email 邀請。

一個人同時屬於多個組織怎麼辦？

MaiAgent 帳號以 Email 為鍵、跨組織共用，成員身分則各組織獨立。SCIM 對某組織建立既有 Email，只會把該帳號加進該組織；停用也只影響該組織。顯示名稱則是帳號層級，經 SCIM 改名會反映到所有組織。