Xác thực và scope

API key, scope và những thao tác chỉ dành cho phiên đăng nhập web.

API key

Gửi key trong header:

Authorization: Bearer agm_live_xxxxxxxx

• Key hiện một lần khi tạo. Hệ thống chỉ lưu băm, không khôi phục được.
• Thu hồi key có hiệu lực ngay.
• Key gắn với một workspace. Key của workspace A không bao giờ thấy dữ liệu workspace B (kể cả khi đoán được id: trả 404).
• Thiếu hoặc sai key: 401 UNAUTHORIZED.

Scope

Scope	Cho phép
accounts:read	Xem danh sách và trạng thái nick
messages:read	Đọc hội thoại, tin nhắn, tải media
messages:write	Gửi tin, reaction, thu hồi, upload media, đánh dấu đã đọc
contacts:read	Danh bạ, tìm người, xem hồ sơ
friends:read	Xem yêu cầu kết bạn
friends:write	Gửi, chấp nhận, từ chối yêu cầu kết bạn

Không có scope *. Nên cấp key theo quyền tối thiểu: một agent chỉ trả lời tin cần accounts:read, messages:read, messages:write. Thiếu scope: 403 FORBIDDEN_SCOPE.

Chỉ dành cho phiên đăng nhập web

API key không thêm/xoá nick, đổi proxy, quản lý API key hay webhook endpoint. Các thao tác này chỉ làm được trong dashboard. Đây là chủ ý: một key bị lộ không thể được dùng để chiếm nick hay đổi đường ra mạng.

Idempotency

Mọi POST nhận header Idempotency-Key. Cùng key và cùng body trong 24 giờ trả lại đúng phản hồi cũ. Cùng key khác body hoặc khác đường dẫn (ví dụ tài khoản khác): 409 (idempotency_key_reused). Phản hồi 202 (đang chờ) không được lưu. Riêng gửi tin còn có client_msg_id (bắt buộc), xem Khái niệm.

Rate limit của API

600 request mỗi phút mỗi key (header X-RateLimit-*). Vượt: 429 kèm Retry-After. Đây là giới hạn riêng, tách khỏi giới hạn gửi tin của kênh, xem Rate limit và anti-ban.