Xác thực và token

API công khai được xác thực bằng token truy cập cá nhân (PAT). Một token được gắn với tài khoản và hoạt động trên tất cả các thực thể của bạn trong phạm vi các scopes đã cấp.

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 mbp_TOKEN_CUA_BAN

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_….

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.

Tiếp theo