Agent Tokens API Reference

🔑 Agent Tokens API Reference

Thông tin nhanh

Mục đích: Cấp phát và quản lý token cho AI Agent (OpenFang/OpenClaw)

Auth (manage): JWT Bearer token (Admin routes, RBAC: settings:r/w)

Auth (use): Header X-Agent-Token trên Agent API endpoints

Security: Token hash SHA-256, hiển thị một lần duy nhất

Rate Limit: Cấu hình per-token (10-1000 req/phút)

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

Scopes Reference

Scope	Quyền	Dùng cho
`leads:read`	Tìm kiếm, đọc leads	`crm_search`
`leads:write`	Tạo mới, cập nhật leads	`crm_create_lead`, `crm_update_lead`
`bookings:read`	Đọc bookings	`crm_get_bookings`
`bookings:write`	Tạo/cập nhật bookings	(reserved)
`calls:read`	Đọc call logs	(reserved)
`calls:write`	Ghi nhận cuộc gọi	`crm_log_call`
`customers:read`	Đọc customers	(reserved)
`customers:write`	Tạo/cập nhật customers	(reserved)
`messages:write`	Gửi/log tin nhắn	`crm_send_message`
`analytics:read`	Đọc analytics	`crm_get_analytics`
`*`	Toàn quyền	Full access

Agent Types

Type	Mô tả
`openfang`	Token cho OpenFang agent
`openclaw`	Token cho OpenClaw agent
`custom`	Token cho hệ thống tích hợp khác

Management Endpoints

Danh sách Agent Tokens

GET /api/settings/agent-tokens

Auth: JWT Bearer · RBAC: settings:r

Response 200:

{
  "agent_tokens": [
    {
      "id": "uuid",
      "name": "Sales Agent - OpenFang",
      "token_prefix": "agent_abc123d",
      "scopes": ["leads:read", "leads:write", "calls:write", "analytics:read"],
      "rate_limit": 60,
      "agent_type": "openfang",
      "is_active": true,
      "last_used_at": "2026-03-17T09:30:00Z",
      "created_at": "2026-03-15T10:00:00Z",
      "created_by_name": "Admin"
    }
  ]
}

Tạo Agent Token mới

POST /api/settings/agent-tokens

Auth: JWT Bearer · RBAC: settings:w

Request Body:

{
  "name": "Sales Agent - OpenFang",
  "scopes": ["leads:read", "leads:write", "calls:write", "messages:write", "analytics:read"],
  "rate_limit": 60,
  "agent_type": "openfang"
}

Field	Type	Bắt buộc	Mô tả
`name`	string	✅	Tên mô tả token
`scopes`	string[]	❌	Danh sách scopes (default: `["leads:read"]`)
`rate_limit`	number	❌	Requests/phút (default: 60, min: 10, max: 1000)
`agent_type`	string	❌	`openfang`, `openclaw`, `custom` (default: `custom`)

Response 201:

{
  "agent_token": {
    "id": "uuid",
    "name": "Sales Agent - OpenFang",
    "token": "agent_abc123def456ghi789...",
    "token_prefix": "agent_abc123d",
    "scopes": ["leads:read", "leads:write", "calls:write", "messages:write", "analytics:read"],
    "rate_limit": 60,
    "agent_type": "openfang",
    "created_at": "2026-03-17T10:00:00Z"
  },
  "message": "Save this token now. It will not be shown again."
}

Thu hồi Agent Token

DELETE /api/settings/agent-tokens/:id

Auth: JWT Bearer · RBAC: settings:w

Response 200:

{ "ok": true }

Best Practices

Principle of Least Privilege: Chỉ cấp scopes cần thiết. Ví dụ agent chỉ làm analytics → chỉ cần analytics:read.
Separate tokens per agent: Mỗi agent/hệ thống nên có token riêng để audit và thu hồi riêng lẻ.
Monitor last_used_at: Token lâu không dùng nên thu hồi.
Rate limit phù hợp: Agent chạy cron 30 phút → 60 req/phút đủ. Agent real-time chat → tăng lên 200-500.
Xử lý 429: Khi bị rate limit, đợi 60 giây rồi thử lại.