授權與權杖
授權程式存取 GetMyBot:建立個人權杖、選擇帳號空間,並只開放所需操作。
本頁內容
個人存取權杖讓程式無須知道你的密碼,也能操作 GetMyBot。文件中簡稱 PAT。例如讀取機器人清單需要 bots:read,建立反應需要 reactions:write。
建立時要選擇一個帳號空間(cabinet)及所需的權限範圍(scopes)。權杖只適用於該帳號空間,且不能取得超過持有人原有的權限。第一次呼叫見 API 快速入門。
建立權杖
在個人帳號的權杖區建立 PAT。完整值只在建立時顯示一次,請妥善保存。伺服器只儲存雜湊,無法找回;遺失時請建立新權杖並刪除舊權杖。所有 PAT 都以 mbp_ 開頭。
傳送權杖
每個請求都在 HTTP Authorization 標頭使用 Bearer 方式:
Authorization: Bearer <個人權杖>
把 <個人權杖>(含尖括號)替換為完整的 mbp_… 值,無須再加一次前綴。MCP 伺服器只接受 PAT,專案 API 權杖(mb_live_…)不能使用。網頁管理介面的短效 JWT 也使用同一種標頭,但程式整合應使用 PAT。
權杖所屬帳號空間
一個 PAT 只在一個帳號空間運作,預設為你的空間。若你是其他空間的成員,建立時也可選擇它:API 的 POST /api/tokens 請求體使用 account_id;管理介面可在到期時間上方的下拉清單選擇。GET /api/account/cabinets 列出可用的帳號空間。
- 使用該權杖呼叫
GET /api/bots,只會取得所選空間的機器人,不會混入你自己或第三個空間的機器人。 - 其他空間的機器人回傳
404,避免藉 ID 查出它是否存在。 - 權限仍以你在該空間的角色和個別機器人權限為準;PAT 只能縮小可見範圍,不能擴權。
- 其他空間的帳務
/api/billing/*需要該空間的billing.read;建立專案需要bots.create。權限範圍*也不能補上帳號空間權限。 - 若你被移出該空間,權杖從下一次請求起立即失效,無須另行撤銷。
僅透過個別機器人取得的空間
GET /api/account/cabinets 的 source 欄位可為:
self:你自己的空間。account:你是空間成員,權限由角色決定。bot:你只能存取空間中的特定機器人,沒有整個空間的權限。
source: "bot" 時,個別機器人的操作仍依其授權執行,但連接新機器人、帳務等整個空間的操作會被拒絕。REST 回傳 403 和 {"error":"missing cabinet right"};若已是成員但缺少特定權限,則為 missing cabinet right: <權限>。MCP 會回傳 permission denied: missing cabinet right,例如 connect_bot 需要 bots.create,帳務工具需要 billing.read 或 billing.write。
需要權限時,請空間擁有者在帳號空間存取設定邀請你。接受邀請後,既有權杖從下一次請求起就會依新權限運作,無須重發。這項功能推出前簽發的權杖綁定你自己的空間;若過去用它操作其他空間分享的機器人,須另建對應空間的權杖。
權限範圍(scopes)
範圍格式為 資源:動作,讀取通常用 :read,修改用 :write:
| 範圍 | 允許操作 |
|---|---|
bots:read、bots:write | 機器人、設定、同步和機器人權杖 |
reactions:read、reactions:write | 反應、匯入、公式測試、關聯和順序 |
labels:read、labels:write | 訂閱者標籤 |
collections:read、collections:write | 集合與記錄 |
flows:read、flows:write | 流程 |
integrations:read、integrations:write | 整合、連接與憑證 |
media:write | 上傳媒體庫 |
templates:read、templates:write | 機器人範本 |
settings:read、settings:write | 設定 |
subscribers:read | 訂閱者及對話歷史(唯讀) |
broadcasts:write | 群發及管理 |
stats:read | 統計與分析 |
billing:read | 餘額與方案(唯讀) |
* 可存取整個公開端點集合,但仍受使用者原有權限限制。
權杖可用與不可用的功能
PAT 只適用於建立和管理機器人的端點。登入、註冊、手機端點、付款及儲值、通知、稽核記錄、客服對話傳訊、傳入 Webhook、付款回呼和 WebSocket 只供網頁工作階段等其他方式使用。以 PAT 請求這些路徑會回傳 401 或 403;缺少某個路徑所需 scope 時則回傳 403。詳見錯誤。
AI 代理功能的權限範圍
managed_ai:invoke、managed_ai:usage:read:呼叫共用的 AI 供應商介面及查看用量。copilot:use:使用 Copilot 建議;診斷另需journey:read,修改流程結構還需journey:edit。journey:read、journey:edit:流程分析、執行說明、Flow Intelligence 與 Explainable Replay。- Meta 帳號連接使用整合和機器人的 scope,同時檢查帳號空間及個別機器人權限。
MCP 遵守相同的權限檢查。連接 MCP 不會擴大 PAT 可存取的帳號空間或機器人範圍。