把 MaiGPT 加進您的系統

把 MaiGPT 加進您自己的系統、給組織成員使用的端到端指南：從開通成員、換發 token、前端嵌入到登出與驗收，一頁讀完照著做

這一頁給「我們的系統要加上 MaiGPT」的工程師從頭讀到尾。不管您是企業自己的入口網站、內部工作台，還是替客戶代管的 SaaS，只要使用者是 MaiAgent 組織的成員（員工、承辦人），流程都一樣。每一步把要做的事直接寫在這裡，想深入才點連結。

如果您的使用者是您的客戶、會員或匿名訪客、不是組織成員，MaiGPT 產品本身不能給他們用，請改走自建 AI Agent＋MaiGPT 視窗模式，聯絡人身分對接見軟體廠商整合指南。

全貌

做完之後：員工在您的系統登入，頁面裡直接出現 MaiGPT，能生圖、Deep Research、用連接器，權限、額度、對話歷史都跟著他在 MaiAgent 的成員身分；他不需要另外登入 MaiAgent，也不需要知道 MaiAgent 的存在。

開始前準備

項目	到哪拿
一個 MaiAgent 組織，方案含 MaiGPT 與身分同步	不確定請洽業務
組織 API Key，持有者是組織擁有者或具「組織總覽」管理權限	取得方式見快速上手
MaiGPT 的 Web Chat ID	GET /api/v1/web-chats/ 回傳中名稱為 MaiGPT、accessType 為 web 的那一筆
角色先建好、權限先設好	後台「組織設定 → 組織總覽 → 編輯角色權限」建例如「員工」角色，勾選 MaiGPT 使用權（設定方式）。成員的能力全部來自角色，這步沒做，後面全部白做
決定成員從哪來	下一節三選一

第一步：開通成員

您的使用者要先是 MaiAgent 組織的成員。三種做法，選最省事的那個：

組織裡已經有人在用 MaiAgent？接 SCIM 不會讓他們原本的帳號失效，也不會建立重複帳號；被接管的既有成員之後會跟著您的系統同步。細節見既有帳號與成員會怎樣。

您的系統有使用者管理（推薦）

在您系統新增、修改、停用使用者的事件裡，順手呼叫 MaiAgent 的 SCIM 端點，成員即時一致。

1. 後台「組織設定 → 身份同步」選 SCIM，「連線資訊」分頁複製 Endpoint URL 與 Token（Token 只顯示一次，放伺服器環境變數）

2. 把即時同步頁的 MaiAgentMembers client 放進您的專案，在事件裡呼叫：

members = MaiAgentMembers()   # 讀環境變數 MAIAGENT_SCIM_URL / MAIAGENT_SCIM_TOKEN

# 新增使用者
user.maiagent_member_id = members.on_user_created(
    external_id=user.id, email=user.email, name=user.display_name, groups=["員工"],
)
# 改名、換部門
members.on_user_updated(user.maiagent_member_id, user.id, user.email, user.display_name, ["員工"])
# 停權、離職
members.on_user_deactivated(user.maiagent_member_id)

1. 第一次上線先把既有使用者跑一輪 on_user_created（冪等，批次補建），之後靠事件維持。

只有名單（HR 匯出、Excel、資料庫）

用名單同步工具：準備一份四欄的 CSV 或 JSON（人員編號、Email、姓名、角色），設好 SCIM 連線環境變數，先 --dry-run 看計畫再真跑，之後排程每天跑一次。名單上有的建立或更新、名單上消失的停用。

有 Okta／Entra ID／JumpCloud

把 SCIM 的 Endpoint URL 與 Token 填進 IdP 的 provisioning 設定，IdP 會自動推送使用者與群組。細節見從 IdP 推送。

三件事要記得，都是實際整合時最常卡的：

• 角色名稱對上後台建好的角色：SCIM 建成員時 groups 填的名稱，就是後台那個已設好權限的角色；名稱對不上會自動建一個沒有權限的新角色。

• Email 是帳號的鍵：userName 就是之後換發 token 用的 Email；建立後不能經 SCIM 改 Email。

• SCIM 建的帳號沒有密碼：這條路的員工不會登入 MaiAgent，這正是我們要的；若同時要開放 MaiGPT 網頁版或 App，另設 SSO。

第二步：後端換發成員 token

在您的後端開一支只給已登入使用者呼叫的端點（例如 GET /maigpt-token），內部以組織 API Key 向 MaiAgent 換發該成員的短效 token：

curl -X POST https://api.maiagent.ai/api/v1/members/embed-tokens/ \
  -H "Authorization: Api-Key <您的組織 API Key>" \
  -H "Content-Type: application/json" \
  -d '{"email": "[e-mail]"}'

成功回 201：

{
  "accessToken": "<成員短效 JWT>",
  "organizationId": "8d2f...-...",
  "expiresAt": 1789906401000,
  "member": { "id": "c1a4...", "userId": "5e77...", "email": "[e-mail]", "name": "Alice" }
}

把整份回應原樣回給前端就好。規則與狀態碼：

事實	說明
效期 15 分鐘、不發 refresh token	續期由前端 SDK 自動處理（第三步），您的後端只要「被叫到就換一顆」——每次都換新的，不要快取
token 只能用在 MaiGPT 對話端點	拿去打 /api/v1/ 任何 API 一律 401，外洩也不能碰組織資料
401／403	沒用 Api-Key／Key 的持有者不是擁有者或組織管理員
404	這個 Email 不是本組織的啟用成員——第一步沒做、或已被停用
每次換發都留稽核紀錄	組織的 API 請求紀錄可查，回應中的 token 不會被記錄

參數與更多細節見成員 token 換發。

第三步：前端嵌入

在要放 MaiGPT 的頁面加入嵌入碼，auth.getToken 指向第二步的端點；其餘都交給 SDK（初始化時取一次 token、到期前自動再取、同一則對話續用）：

<div id="maigpt-container" style="height: 720px;"></div>
<script>
  window.maiagentChatbotConfig = {
    webChatId: '<MaiGPT 的 Web Chat ID>',
    baseUrl: 'https://chat.maiagent.ai/web-chats',
    enabledWindowModes: ['maigpt'],
    targetElement: '#maigpt-container',
    maigptTitle: 'Acme GPT',            // 選填：左上角品牌名
    locale: 'zh-TW',                    // 選填：介面語系
    auth: {
      getToken: async () => {
        const res = await fetch('/maigpt-token', { credentials: 'include' })
        const { accessToken, organizationId, member } = await res.json()
        return { accessToken, organizationId, sourceId: member.userId }
      },
    },
  }
</script>
<script src="https://chat.maiagent.ai/js/embed.min.js" defer></script>

sourceId 一定要填回應裡的 member.userId，不是 member.id、也不是您系統的使用者編號。MaiGPT 靠它把對話對應到成員，填錯會變成匿名對話、看不到該成員的歷史。

容器要自己給高度；SPA 要等容器 mount 後再載入 SDK；baseUrl 與 SDK 網址是 SaaS 位址，私有部署請換成您的網域。版面與其他參數見 MaiGPT 模式嵌入。

第四步：登出與離職

事件	您要做的事	結果
使用者登出您的系統	前端呼叫 MaiAgent.auth.signOut()	iframe 清掉身分並停止續期；已發出的 token 最多再存活 15 分鐘
使用者離職／停權	第一步的停用（on_user_deactivated、名單移除、IdP 停用）	之後換發回 404，嵌入頁自然失效；對話與額度紀錄保留
復職	第一步的重新啟用	角色與歷史恢復

第五步：驗收

依序確認，每一項都有明確的判斷點：

1. 成員存在且有角色：後台「成員管理」看得到這個人，角色是您設好權限的那個。

2. 換發成功：第二步 curl 回 201；換一個不存在的 Email 回 404。

3. 能對話：嵌入頁開啟 MaiGPT、送一句話得到回覆；用該成員登入 MaiGPT 網頁版（若有 SSO）或後台對話紀錄能看到這則對話。

4. 能力對：請它生一張圖；若角色有開連接器與 Deep Research，入口會出現。

5. 續期無感：頁面停留超過 15 分鐘再送訊息，不用重新整理、同一則對話繼續。

6. 登出生效：signOut() 後再送訊息被拒；停用該成員後第二步回 404。

上線後

• SCIM Token 與 API Key 輪換：SCIM Token 建立超過 180 天後台會提醒；重新產生後舊的立即失效，記得同步更新伺服器環境變數。

• 方案容量：成員數影響內建 Agent 席次與每成員 Credits 額度，見成員 Credits 額度管理。

• 稽核：每次換發 token 都在組織的 API 請求紀錄；SCIM 的每次同步在後台「身份同步 → 同步紀錄」。

出錯時

現象	原因	處理
換發回 404	Email 不是本組織啟用成員	回第一步確認成員存在、未停用、Email 相同（大小寫不分）
換發回 403	API Key 持有者不是擁有者也沒有組織管理權限	換用管理員發的 Key
聊天視窗「建立對話失敗（400）您沒有權限使用 MaiGPT」	成員的角色沒有 MaiGPT 使用權，或 auth 沒帶到	後台角色權限開 MaiGPT；確認 getToken 有回 accessToken 與 organizationId
對話是匿名的、看不到歷史	sourceId 填錯	用 member.userId
15 分鐘後送訊息失敗	getToken 沒被呼叫或失敗（看瀏覽器 console 的 [MaiAgent] 錯誤）	確認端點對已登入使用者可用、回應格式正確
成員建好但什麼都不能用	沒進任何角色，或角色權限是空的	後台角色權限設定；SCIM 用相同名稱指派
改了 Email 沒生效	SCIM 不允許變更 Email	後台修改，或停用舊帳號以新 Email 建立

更多 SCIM 錯誤碼見名單同步工具的錯誤對照。

深入閱讀

• 成員開通：SCIM／邀請／SSO — SCIM API 完整參考、三條路對照

• 即時同步：在使用者事件中呼叫／名單同步工具

• 串接 MaiGPT：選對 Agent、補齊能力 — MaiGPT 產品 vs 自建 Agent、成員身分嵌入的完整參數

• Web Chat 嵌入與 SDK／MaiGPT 模式嵌入