🔑 API Keys cho AI Agent

Tạo key: salehay.com/app → Cài đặt → API Keys → +Dùng key: Header X-Agent-Token: sk_live_xxx trên Agent API endpoints Bảo mật: Key hash SHA-256, chỉ hiển thị 1 lần khi tạo

Xem thêm: Agent API · Cài đặt Agent

---

📌 Thông tin quan trọng

• Key có dạng sk_live_xxx... — tạo từ trang API Keys trong Admin
• Key dùng cho cả Agent API (/api/agent/*) và Public Lead API (/api/public/leads)
• Header: X-Agent-Token: sk_live_xxx (cho Agent API) hoặc X-API-Key: sk_live_xxx (cho Public API)
• Mặc định scope leads:create — liên hệ admin để update scope * (toàn quyền) cho agent

Scopes

Scope	Quyền	MCP Tool
leads:read	Tìm kiếm leads	crm_search
leads:write	Tạo/cập nhật leads	crm_create_lead, crm_update_lead
bookings:read	Xem bookings	crm_get_bookings
calls:write	Ghi cuộc gọi	crm_log_call
messages:write	Gửi tin nhắn	crm_send_message
analytics:read	Xem analytics	crm_get_analytics
*	Toàn quyền	Tất cả tools

💡 Tip: Tạo key với scope * cho agent, scope giới hạn cho tích hợp bên thứ ba.

---

Quản lý qua Admin UI

Tạo Key

1. Vào salehay.com/app
2. Thêm → Cài đặt → API Keys
3. Bấm + → đặt tên → Tạo
4. ⚠️ Copy key ngay! Key chỉ hiển thị 1 lần

Xóa Key

Bấm icon 🗑️ bên cạnh key → key bị vô hiệu hóa ngay lập tức.

Agent đang dùng key bị xóa sẽ nhận lỗi 401.

---

Management API (cho developer)

Danh sách Keys

GET /api/settings/api-keys
Auth: JWT Bearer · RBAC: settings:r

Tạo Key mới

POST /api/settings/api-keys
Auth: JWT Bearer · RBAC: settings:w

{
  "name": "OpenFang Sales Agent",
  "scopes": ["*"],
  "rate_limit": 100
}

Response 201:

{
  "api_key": {
    "id": "uuid",
    "key": "sk_live_523cc2765eee...",
    "name": "OpenFang Sales Agent",
    "scopes": ["*"],
    "rate_limit": 100
  },
  "message": "Save this key now. It will not be shown again."
}

Xóa Key

DELETE /api/settings/api-keys/:id
Auth: JWT Bearer · RBAC: settings:w

---

Best Practices

1. 1 key / 1 agent: Mỗi agent có key riêng → dễ audit, xóa riêng lẻ
2. Scope tối thiểu: Agent chỉ đọc? → analytics:read, bookings:read
3. Monitor last_used_at: Key lâu không dùng → nên xóa
4. Rate limit phù hợp: Agent cron 30 phút → 100 req/phút đủ
5. Mất key? Tạo key mới, xóa key cũ — không thể xem lại key đã tạo