Xác thực

Tạo khóa API và xác thực yêu cầu bằng header Bearer.

Cập nhật 23 tháng 10, 2026

Điều kiện tiên quyết: Bạn cần một tài khoản có quyền truy cập tổ chức muốn truy vấn.

Tạo khóa API

Khóa API là của cá nhân — được tạo từ chính tài khoản của bạn, không phải từ khu vực quản trị tổ chức, và mỗi khóa có đúng quyền truy cập của người dùng đã tạo ra nó.

Nhấp ảnh đại diện ở cuối thanh bên → Cài đặt, rồi mở tab Khóa API.
Chọn Tạo khóa API.
Nhập tên giúp nhận biết tích hợp (ví dụ: “CAM Plugin”, “ERP Sync”).
Chọn Tạo. Khóa chỉ hiển thị một lần — sao chép ngay, vì khóa sẽ không hiển thị lại.

Bạn có thể tạo nhiều khóa (một người dùng có thể có nhiều khóa API) và thu hồi bất kỳ khóa nào ngay trên màn hình đó.

Xác thực yêu cầu

Đưa khóa vào header Authorization của mọi yêu cầu:

Authorization: Bearer <your-token>

Yêu cầu không có khóa hợp lệ nhận phản hồi 401 Unauthorized, kèm header WWW-Authenticate: Bearer trong phản hồi:

{ "errors": ["Access denied"] }

Tìm ID tổ chức

Phần lớn endpoint cần tham số đường dẫn organization_id. Lấy giá trị này từ:

GET /v1/organizations
Authorization: Bearer <your-token>

Phản hồi — một ánh xạ từ tên tổ chức sang ID:

{
  "Acme Manufacturing": 12,
  "Acme Tooling": 15
}

Dùng ID dạng số trong mọi yêu cầu tiếp theo:

GET /v1/organizations/12/machines
Authorization: Bearer <your-token>

Phạm vi phân quyền

Có khóa hợp lệ cho đúng tổ chức chưa có nghĩa là bạn xem được mọi bản ghi trong đó. Quyền truy cập còn được giới hạn theo vai trò của bạn với từng loại tài nguyên trong tổ chức:

Quản trị viên site, và người dùng có vai trò Quản trị viên (admin) hoặc Người quản lý (manager) với một tài nguyên, xem được mọi bản ghi phù hợp trong tổ chức.
Người dùng có vai trò Người dùng (user) với một tài nguyên chỉ xem được các bản ghi do chính họ tạo (user_id trùng với người sở hữu khóa).

Phạm vi này áp dụng riêng cho từng loại tài nguyên (ví dụ: vai trò của bạn với parts và với machines là độc lập) và được kiểm tra ở mọi endpoint danh sách và chi tiết, không chỉ ở các thao tác ghi.

Phản hồi lỗi

Yêu cầu thất bại với:

Mã trạng thái	Ý nghĩa
`401 Unauthorized`	Thiếu khóa hoặc khóa không hợp lệ, hoặc người sở hữu khóa không được phép thực hiện thao tác này — cả hai trường hợp đều dùng `401`, không phải `403`. Thông báo lỗi khác nhau: khóa thiếu/không hợp lệ nhận `"Access denied"`; không đủ quyền nhận `"You are not authorized to perform this action"`. Một `organization_id` không tồn tại nhận lỗi không đủ quyền, như một tổ chức mà khóa không truy cập được
`404 Not Found`	Bản ghi không tồn tại hoặc thuộc tổ chức khác
`422 Unprocessable Entity`	Kiểm tra dữ liệu không đạt — thân phản hồi chứa lỗi theo từng trường

Xem Lỗi để biết định dạng lỗi đầy đủ, kể cả một điểm không nhất quán trong thân phản hồi 404 mà bạn nên biết.