Cơ chế xác thực trong Perfex CRM API: Quản lý Token & Phân quyền truy cập

Last updated on Jul 10, 2026 4:22 AM

Kiến trúc bảo mật API

Mỗi yêu cầu gọi dữ liệu qua Data Builder API đều đi qua một quy trình middleware bảo mật gồm 7 lớp trước khi tiếp cận dữ liệu CRM của bạn. Xác thực danh tính nằm ở lớp thứ 3, ngay sau lớp chống tấn công DDoS và lớp kiểm tra CORS.

Xác thực qua Bearer Token

Tất cả các yêu cầu gọi API đều bắt buộc phải kèm theo một token hợp lệ đặt ở tiêu đề Authorization:

Authorization: Bearer dba_51d5xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxd186

Các token được khởi tạo tại mục Admin > Data Builder > API Tokens. Mỗi token được định nghĩa các thông số bảo mật:

Phạm vi truy cập (Scopes) – Những tài nguyên token được phép gọi (tables, views, write)
Phân quyền thao tác bảng – Kiểm soát chi tiết quyền CRUD trên từng bảng dữ liệu (đọc/tạo mới/cập nhật/xóa)
Danh sách IP trắng (IP whitelist) – Giới hạn dải địa chỉ IP được phép truy cập dựa trên định dạng CIDR
Danh sách tên miền trắng (Domain whitelist) – Định nghĩa các Origin/Referer tên miền được phép gọi API
Giới hạn tần suất (Rate limit) – Số lượng yêu cầu tối đa mỗi phút (mặc định: 60)
Thời hạn sử dụng (Expiration) – Thiết lập ngày hết hạn tùy chọn cho token

Endpoint kiểm tra xác thực (Auth Test)

Kiểm tra trạng thái hoạt động của token mà không làm lộ các dữ liệu nhạy cảm:

GET https://databuilder.polyxgo.com/api/v1/auth/test
Authorization: Bearer YOUR_TOKEN

Response:
{
  "status": "ok",
  "token_name": "Zapier Integration",
  "scopes": ["tables", "views"],
  "tables_count": 12,
  "server_time": "2026-04-26T12:00:00+07:00"
}

Endpoint này được thiết kế tối ưu phục vụ kết nối ban đầu trên Zapier, Make.com, và n8n.

Chữ ký HMAC-SHA256 (HMAC-SHA256 Request Signing)

Đối với môi trường sản xuất yêu cầu mức độ bảo mật cao nhất, bạn hãy kích hoạt tính năng ký xác thực HMAC cho token của mình. Khi đó, mỗi yêu cầu API bắt buộc phải đính kèm tiêu đề X-Timestamp và X-Signature. Vui lòng tham khảo mục Xác thực trong Tài liệu API để xem ví dụ triển khai bằng PHP, JavaScript và Python.

Bỏ qua xác thực cho Quản trị viên (Admin Session Bypass)

Các tài khoản quản trị viên Perfex CRM đã đăng nhập hệ thống có thể sử dụng trực tiếp API Explorer sandbox mà không cần truyền Bearer token. Middleware sẽ tự động phát hiện phiên đăng nhập của admin và cấp quyền truy cập tức thì.