API REST: Xác thực và sử dụng

Last updated on Jun 24, 2026 01:40

PolyCMS cung cấp API RESTful toàn diện ngay lập tức, cho phép bạn xây dựng giao diện người dùng không đầu, ứng dụng di động hoặc tích hợp với các công cụ của bên thứ ba (như hệ thống Zapier, CRM hoặc ERP).

API được đặt ở tiền tố /api/v1.

Hệ thống xác thực

PolyCMS sử dụng Laravel Sanctum để quản lý xác thực API. Nó hỗ trợ hai phương thức chính tùy thuộc vào trường hợp sử dụng của bạn:

Xác thực SPA (Cookie): Được sử dụng bởi Bảng quản trị Vue 3 tích hợp. Nó dựa vào cookie phiên và bảo vệ CSRF.

Xác thực mã thông báo API: Được sử dụng cho các ứng dụng bên ngoài, ứng dụng dành cho thiết bị di động và mô-đun "Sandbox Remote". Phương pháp này sử dụng mã thông báo Bearer.

Hướng dẫn này tập trung vào Xác thực mã thông báo API để tích hợp bên ngoài.

graph TD Client[Khách hàng gửi yêu cầu HTTP] --> HeaderCheck{Có Header Authorization không?} HeaderCheck -->|Không| Unauth[Trả về mã 401 Unauthorized] HeaderCheck -->|Có| Extract[Trích xuất Bearer Token] Extract --> QueryDB[Truy vấn CSDL tìm mã thông báo cá nhân] QueryDB --> TokenCheck{Mã thông báo tồn tại và chưa hết hạn?} TokenCheck -->|Không| Unauth TokenCheck -->|Có| ResolveUser[Xác định Người dùng đã xác thực] ResolveUser --> PermissionCheck[Kiểm tra Quyền hạn và Phạm vi] PermissionCheck --> AuthCheck{Được cấp quyền?} AuthCheck -->|Không| Forbidden[Trả về mã 403 Forbidden] AuthCheck -->|Có| Process[Xử lý logic của Endpoint] Process --> SuccessResponse[Trả về phản hồi JSON]

Tạo mã thông báo truy cập cá nhân (PAT)

Để truy cập các điểm cuối được bảo vệ, bạn phải tạo mã thông báo.

Đăng nhập vào Bảng quản trị PolyCMS.

Điều hướng đến Cài đặt > Mã thông báo API (hoặc nhấp vào Hồ sơ người dùng của bạn).

Nhấp vào Tạo mã thông báo mới.

Đặt tên dễ nhận biết cho mã thông báo (ví dụ: "Ứng dụng di động" hoặc "Tích hợp Zapier").

Bước quan trọng: Bạn sẽ chỉ được hiển thị mã thông báo văn bản thuần túy một lần. Sao chép nó ngay lập tức và lưu trữ nó trong trình quản lý mật khẩu an toàn.

Tạo yêu cầu API

Sau khi có mã thông báo, bạn phải đưa mã đó vào tiêu đề Ủy quyền của mọi yêu cầu HTTP mà bạn thực hiện với API PolyCMS.

Ví dụ: Tìm nạp người dùng hiện tại (cURL)

curl -X GET https://polycms.org/api/v1/user \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_PLAIN_TEXT_TOKEN_HERE"

Ví dụ: Tạo một bài viết (JavaScript/Fetch)

const response = await fetch('https://polycms.org/api/v1/posts', {
  method: 'POST',
  headers: {
    'Accept': 'application/json',
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_PLAIN_TEXT_TOKEN_HERE'
  },
  body: JSON.stringify({
    title: 'Hello via API',
    slug: 'hello-via-api',
    content_raw: '{"blocks":[{"type":"paragraph","data":{"text":"Created via REST!"}}]}',
    status: 'draft'
  })
});

const data = await response.json();
console.log(data);

Các phương pháp bảo mật tốt nhất

Chỉ HTTPS: Luôn thực hiện các yêu cầu API qua kết nối https:// an toàn. Việc gửi mã thông báo Bearer qua HTTP sẽ khiến hệ thống của bạn bị chặn.

Thu hồi mã thông báo: Nếu bạn nghi ngờ mã thông báo đã bị xâm phạm, hãy thu hồi ngay mã thông báo đó trong Bảng điều khiển quản trị trong Cài đặt > Mã thông báo API.

Quyền: Hiện tại, PAT kế thừa các quyền chính xác của người dùng đã tạo chúng. Đảm bảo bạn tạo mã thông báo bằng tài khoản chỉ có các đặc quyền cần thiết cho tác vụ (ví dụ: không sử dụng tài khoản Quản trị viên để tích hợp chỉ đọc).