Xác thực & Phân quyền

Hệ thống phân chia rõ ràng giữa các tài nguyên công khai (Public) phục vụ hiển thị ở frontend và các tài nguyên quản trị (Admin) yêu cầu bảo mật.

---

🌎 Truy cập Công khai (Public Access)

Hầu hết các API đọc dữ liệu được thiết kế công khai để frontend có thể fetch trực tiếp mà không cần cấu hình API key phức tạp:

• Các route áp dụng:
  • /api/customers/:slug
  • /api/portfolio/:slug
  • /api/transactions/:slug
  • /api/stats/:slug
  • /api/analytics/:slug
  • /api/aggregate/:slug
  • /api/brokers
• Cơ chế bảo mật: Dữ liệu được cô lập theo slug định danh duy nhất của từng khách hàng. Slug được sinh ngẫu nhiên hoặc băm để đảm bảo tính riêng tư, ngăn chặn việc quét dữ liệu hàng loạt (Scraping).

---

🔒 Truy cập Quản trị (Admin Access)

Các API làm thay đổi trạng thái hệ thống hoặc thực hiện các tác vụ nặng bắt buộc phải được bảo mật bằng cơ chế xác thực API Key thông qua Custom Header.

• Route áp dụng: POST /api/sync (Đồng bộ dữ liệu thủ công).
• Cơ chế xác thực: Sử dụng header X-Admin-Key.
• Cấu hình Key: API Key được lưu trữ dưới dạng biến môi trường bảo mật (Secrets) ADMIN_API_KEY trên Cloudflare Workers.

Cách gửi Request có Xác thực

Bạn cần thêm header X-Admin-Key kèm theo giá trị bí mật của key vào HTTP request:

curl -X POST "https://api.hocchungkhoan.com.vn/api/sync" \
  -H "X-Admin-Key: your-secret-admin-key"

Xử lý lỗi xác thực

Nếu không truyền Header này hoặc giá trị truyền vào không khớp với cấu hình, API sẽ lập tức trả về mã trạng thái 401 Unauthorized:

{
  "success": false,
  "error": "Unauthorized"
}