Xác thực và scope - Agentme

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.