> ## Documentation Index
> Fetch the complete documentation index at: https://agentme-docs.vipcrm.net/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```http theme={null}
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](https://agentme-docs.vipcrm.net/concepts.md).

## 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](https://agentme-docs.vipcrm.net/rate-limits-and-anti-ban.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.