Xác thực và token
Cấp quyền truy cập GetMyBot cho chương trình: tạo token cá nhân, chọn tài khoản và chỉ cho phép thao tác cần thiết.
Trên trang này
Token cá nhân cho chương trình truy cập GetMyBot mà không cần biết mật khẩu của bạn. Tài liệu gọi nó là PAT (Personal Access Token). Chẳng hạn, bots:read cho phép đọc danh sách bot, còn reactions:write cho phép tạo phản ứng.
Khi tạo token, hãy chọn một tài khoản quản trị và các phạm vi truy cập (scopes) cần thiết. Token chỉ hoạt động trong tài khoản đã chọn và không có quyền vượt quá tài khoản của bạn. Để thử yêu cầu đầu tiên, xem Bắt đầu nhanh API.
Tạo token
Token cá nhân được tạo trong trang cá nhân, trong mục token cá nhân. Giá trị token chỉ hiển thị một lần khi tạo — hãy lưu ở nơi an toàn. Trên máy chủ, token chỉ được lưu ở dạng hash, không thể khôi phục; nếu mất — hãy tạo mới và xóa cái cũ.
Tất cả token cá nhân đều bắt đầu bằng tiền tố mbp_.
Truyền token
Token được truyền trong mỗi yêu cầu qua HTTP header Authorization theo scheme Bearer:
Authorization: Bearer <TOKEN_CÁ_NHÂN>
Thay cả phần trong dấu ngoặc góc bằng toàn bộ token đúng như khi được cấp, gồm tiền tố mbp_. Không thêm mbp_ lần nữa. Máy chủ MCP chỉ nhận token cá nhân; token API của dự án (mb_live_…) không dùng được cho MCP.
Header tương tự cũng được dùng để truy cập phiên từ trang web (ở đó là JWT ngắn hạn), nhưng để tích hợp, hãy dùng chính xác token cá nhân mbp_….
Tài khoản quản trị của token
Token hoạt động trong đúng một tài khoản quản trị. Mặc định là tài khoản của bạn. Nếu được mời vào tài khoản khác, bạn có thể chọn tài khoản đó khi tạo token: trường account_id trong POST /api/tokens, hoặc danh sách chọn phía trên thời hạn token trong giao diện. GET /api/account/cabinets trả danh sách tài khoản có thể chọn.
Điều này có nghĩa là:
GET /api/botschỉ trả bot của tài khoản đã chọn, không trả bot trong tài khoản riêng của bạn hay tài khoản thứ ba.- Gọi một bot thuộc tài khoản khác trả
404, như với bot của người ngoài; token không cho biết ID đó có tồn tại ngoài tài khoản hay không. - Token không tăng quyền của bạn mà chỉ giới hạn ở một tài khoản. Quyền đối với bot còn phụ thuộc vai trò trong tài khoản và quyền riêng trên bot đó.
- Token cho tài khoản của người khác dùng quyền của chính bạn trong tài khoản đó. Đọc hóa đơn qua
/api/billing/*cần quyềnbilling.read; tạo dự án cầnbots.create. Phạm vi token*không tự cấp các quyền này. - Nếu quyền truy cập tài khoản bị thu hồi, token ngừng hoạt động ngay từ yêu cầu tiếp theo; không cần thu hồi token riêng.
Tài khoản chỉ được truy cập qua một bot
Mỗi tài khoản trong GET /api/account/cabinets có trường source:
self: tài khoản của bạn;account: bạn được mời vào tài khoản, quyền do vai trò quyết định;bot: bạn chỉ được cấp quyền trên một bot trong tài khoản; không có quyền trên toàn tài khoản.
Với source: "bot", bạn có thể thao tác trên bot đó trong phạm vi quyền riêng của mình. Việc của cả tài khoản, như kết nối bot mới hoặc thanh toán, bị từ chối. REST trả 403 với {"error":"missing cabinet right"}; nếu bạn là thành viên nhưng thiếu quyền cụ thể, lỗi là missing cabinet right: <quyền>. MCP trả lỗi công cụ permission denied: missing cabinet right. Ví dụ, connect_bot cần bots.create; công cụ thanh toán cần billing.read hoặc billing.write.
Để có thêm quyền, chủ tài khoản mời bạn trong Quyền truy cập tài khoản với quyền phù hợp. Không cần tạo lại token: nó dùng được từ yêu cầu tiếp theo sau khi bạn nhận lời mời.
Token tạo trước khi có khả năng chọn tài khoản vẫn gắn với tài khoản riêng của bạn. Nếu token cũ từng dùng được với bot được chia sẻ từ tài khoản khác, hãy tạo token riêng cho tài khoản đó.
Phạm vi truy cập (scopes)
Token có tập hợp phạm vi truy cập theo định dạng resource:action. Đọc yêu cầu hậu tố :read, thay đổi — :write. Các phạm vi có sẵn:
bots:read,bots:write— bot, cài đặt của chúng, đồng bộ, token bot.reactions:read,reactions:write— phản ứng, import, kiểm tra công thức, liên kết, thứ tự.labels:read,labels:write— nhãn người đăng ký.collections:read,collections:write— bộ sưu tập và bản ghi.flows:read,flows:write— kịch bản.integrations:read,integrations:write— tích hợp, kết nối, thông tin xác thực.media:write— tải lên thư viện media.templates:read,templates:write— template bot.settings:read,settings:write— cài đặt.subscribers:read— người đăng ký và lịch sử đối thoại (chỉ đọc).broadcasts:write— phát đi và quản lý chúng.stats:read— thống kê và phân tích.billing:read— số dư và gói cước (chỉ đọc).
Phạm vi đặc biệt * cho toàn quyền truy cập vào tất cả endpoint công khai.
Những gì có thể và không thể truy cập qua token
Với token cá nhân chỉ có thể truy cập các endpoint xây dựng — những endpoint "giúp xây dựng bot". Không thể truy cập qua PAT (chỉ từ phiên web): đăng nhập và đăng ký, endpoint di động, thanh toán và nạp tiền vào số dư, thông báo, nhật ký kiểm tra, gửi tin nhắn của người điều hành vào cuộc trò chuyện, webhook đầu vào và callback thanh toán, WebSocket. Yêu cầu với token mbp_ đến route như vậy sẽ trả về 401 hoặc 403.
Nếu token thiếu phạm vi cần thiết cho một route cụ thể — sẽ trả về 403. Xem thêm về mã lỗi — trong hướng dẫn về lỗi.
Phạm vi cho tính năng tác nhân AI
managed_ai:invokevàmanaged_ai:usage:read: gọi AI qua giao diện chung của các nhà cung cấp và đọc mức sử dụng.copilot:use: làm việc với đề xuất Copilot. Xem chẩn đoán cầnjourney:read; sửa cấu trúc kịch bản còn cầnjourney:edit.journey:readvàjourney:edit: phân tích kịch bản, giải thích lần chạy, Flow Intelligence và Explainable Replay.- Quản lý kết nối Meta dùng phạm vi của tích hợp và bot, đồng thời kiểm tra quyền trên tài khoản và bot cụ thể.
MCP áp dụng cùng các bước kiểm tra quyền. Kết nối MCP không mở thêm quyền cho token trên tài khoản hoặc bot khác.
Tiếp theo
- Bắt đầu nhanh API — yêu cầu đầu tiên với token.
- Lỗi — ý nghĩa của
401và403. - MCP — cùng token cho giao diện agent.