# ZChat auth.md — AI Agent Registration & Authentication Guide

> **Audience**: AI Agents, LLM Orchestrators, MCP Clients, and Automated Systems interacting with ZChat (https://zachat.vn) and ZChat API Gateway (https://api.zachat.vn).

---

## 1. Overview
ZChat enables autonomous and semi-autonomous AI agents to manage multiple Zalo accounts, orchestrate broadcast messaging, handle team inboxes, and manage customer CRM tags securely.

To interact with protected ZChat endpoints, AI agents must authenticate using either:
1. **OAuth 2.0 Bearer Tokens** (recommended for user-delegated access and third-party platforms)
2. **Permanent API Keys** (recommended for server-to-server daemon agents)

---

## 2. Discovery Endpoints
Agents should inspect the following discovery endpoints before attempting registration or authentication:
- **OAuth Protected Resource Metadata (RFC 9728)**: `https://zachat.vn/.well-known/oauth-protected-resource`
- **OAuth Authorization Server Metadata (RFC 8414)**: `https://zachat.vn/.well-known/oauth-authorization-server`
- **OpenID Connect Discovery**: `https://zachat.vn/.well-known/openid-configuration`
- **JSON Web Key Set (JWKS)**: `https://zachat.vn/.well-known/jwks.json`
- **API Catalog (RFC 9727)**: `https://zachat.vn/.well-known/api-catalog`
- **MCP Server Card (SEP-1649)**: `https://zachat.vn/.well-known/mcp/server-card.json`
- **Agent Skills Discovery**: `https://zachat.vn/.well-known/agent-skills/index.json`

---

## 3. Dynamic Agent Registration
Agents can dynamically register their client identity to obtain automated access credentials.

- **Registration Endpoint**: `POST https://zachat.vn/agent/register`
- **Content-Type**: `application/json`

### Request Example
```json
{
  "client_name": "Claude-Zalo-Sales-Agent",
  "identity_type": "anonymous",
  "credential_types": ["bearer_token", "api_key"],
  "redirect_uris": ["https://agent.example.com/oauth/callback"],
  "grant_types": ["client_credentials", "authorization_code"],
  "scope": "read write chat zalo:message zalo:broadcast"
}
```

### Response Example
```json
{
  "client_id": "agent_cl_984fbc91",
  "client_secret": "zsec_9f823a411e8c78b40a...",
  "api_key": "zchat_live_k82491a...",
  "claim_uri": "https://zachat.vn/agent/claim?code=claim_8410294",
  "token_endpoint": "https://api.zachat.vn/api/auth/token"
}
```

---

## 4. Obtaining Access Tokens
Registered agents can exchange client credentials for short-lived access tokens.

- **Token Endpoint**: `POST https://api.zachat.vn/api/auth/token`
- **Content-Type**: `application/x-www-form-urlencoded` or `application/json`

```http
POST /api/auth/token HTTP/1.1
Host: api.zachat.vn
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=agent_cl_984fbc91&client_secret=zsec_9f823a411e8c78b40a...&scope=chat+zalo:message
```

Response:
```json
{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "chat zalo:message"
}
```

---

## 5. Authenticated Requests
All requests to protected API endpoints and the Model Context Protocol (MCP) stream endpoint must include the token in the `Authorization` header:

```http
GET /api/zalo/sessions HTTP/1.1
Host: api.zachat.vn
Authorization: Bearer eyJhbGciOiJSUzI1NiIs...
```

Alternatively, daemon agents with an API key can pass:
```http
GET /api/zalo/sessions HTTP/1.1
Host: api.zachat.vn
X-API-Key: zchat_live_k82491a...
```

---

## 6. Supported Scopes
- `read`: Đọc thông tin phiên Zalo, danh bạ bạn bè, trạng thái kết nối.
- `write`: Chỉnh sửa ghi chú, gắn nhãn CRM, cập nhật cài đặt.
- `chat`: Nhận webhook tin nhắn đến và gửi tin nhắn phản hồi cho khách hàng.
- `zalo:message`: Gửi tin nhắn văn bản, hình ảnh, file đính kèm qua tài khoản Zalo.
- `zalo:broadcast`: Tạo và khởi chạy chiến dịch gửi tin hàng loạt có giãn cách an toàn.

---

## 7. Revocation & Claim
- **Claim Endpoint**: `https://zachat.vn/agent/claim` — Liên kết quyền của bot với tài khoản tổ chức ZChat.
- **Revocation Endpoint**: `https://zachat.vn/agent/revoke` — Hủy token hoặc vô hiệu hóa API key tức thì.