授權與 Token
公開 API 使用個人存取 Token(PAT)進行授權。一個 Token 繫結至帳號,並在授予的存取範圍內作用於你的所有編輯器資源。
建立 Token
個人 Token 在個人後台的個人 Token 區塊中建立。Token 值僅在建立時顯示一次,請妥善保存。伺服器僅以雜湊形式儲存 Token,無法還原;若遺失,請重新申請並刪除舊 Token。
所有個人 Token 均以 mbp_ 前綴開頭。
傳遞 Token
每個請求均需在 HTTP 標頭 Authorization 中以 Bearer 方式傳遞 Token:
Authorization: Bearer mbp_你的_TOKEN
網頁後台的 Session 存取也使用相同標頭(但為短效 JWT),整合時請使用個人 Token mbp_…。
存取範圍(Scopes)
Token 具有 資源:動作 格式的存取範圍集合。讀取需要 :read 後綴,修改需要 :write。可用的範圍:
bots:read、bots:write— 機器人、其設定、同步、機器人 Token。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— 餘額與方案(唯讀)。
特殊範圍 * 提供對所有公開端點的完整存取權限。
Token 可存取與不可存取的內容
個人 Token 僅可存取編輯器端點——即「協助建構機器人」的端點。以下內容無法透過 PAT 存取(僅限 Web Session):登入與註冊、行動端點、付款與餘額儲值、通知、稽核日誌、客服人員傳送訊息至對話、傳入 Webhook 與付款回呼、WebSocket。使用 mbp_ Token 請求此類路由將回傳 401 或 403。
若 Token 缺少特定路由所需的範圍,將回傳 403。詳細錯誤碼說明請參見錯誤指南。