# Xác thực

Mọi yêu cầu gửi API key qua tham số truy vấn `api_key`:

```bash
curl "https://pos.pages.fm/api/v1/shops/SHOP_ID/orders?api_key=API_KEY"
```

## Hai loại API key

| | API key cửa hàng | API key tài khoản |
|---|---|---|
| Tạo ở | **Cấu hình › Ứng dụng › Webhook/API**, tab **API Key** | **Tài khoản › API Key** |
| Dùng cho | Một cửa hàng | Mọi cửa hàng tài khoản đang tham gia |
| Quyền | Toàn quyền trên Open API của cửa hàng | Đúng quyền của tài khoản tại từng cửa hàng: vai trò, kho, bộ phận, giờ làm, IP được phép |
| Dạng key | Chuỗi ngẫu nhiên | Bắt đầu bằng `pos_user_` |
| Phù hợp | Tích hợp chạy nền giữa hai hệ thống (ERP, website) | Công cụ thao tác thay một người: script cá nhân, [MCP](/developers/mcp) |

Hai loại key gọi cùng các endpoint. Key tài khoản bị chặn ở những thao tác tài khoản đó không có quyền (`403`).

## API key cửa hàng

1. Mở **Cấu hình › Ứng dụng**, chọn **Webhook/API**.
2. Mở tab **API Key**, bấm **Thêm**. Ghi chú mục đích của key để dễ quản lý.
3. Sao chép key và lưu vào nơi an toàn trên máy chủ của bạn.

Xóa key ở cùng danh sách khi không dùng nữa; hệ thống đang dùng key đó sẽ bị từ chối ngay.

## API key tài khoản

1. Mở trang **Tài khoản**, mục **API Key**, bấm **Tạo mới**.
2. Đặt tên theo mục đích dùng (ví dụ "Claude", "Báo cáo hằng ngày").
3. Key chỉ hiện **một lần** sau khi tạo: sao chép ngay.

Một key dùng cho mọi cửa hàng bạn đang tham gia:

- Gọi `GET /shops` để biết các cửa hàng key dùng được; mọi endpoint khác cần `{SHOP_ID}` trong đường dẫn.
- Rời một cửa hàng hoặc bị đổi quyền thì key đổi theo ngay.
- Đổi tên hoặc thu hồi key trong cùng danh sách. API key không dùng để tạo hay thu hồi API key khác.

## Giữ key an toàn

- API key có quyền như mật khẩu: không đưa vào mã chạy trên trình duyệt hay ứng dụng di động, không commit vào git, không gửi qua tin nhắn.
- Gọi Open API từ máy chủ của bạn, đọc key từ biến môi trường hoặc kho bí mật.
- Nghi lộ key: xóa hoặc thu hồi key ngay rồi tạo key mới.
- Nhập sai `api_key` 20 lần trong một phút từ cùng một địa chỉ IP sẽ bị khoá 5 phút (`429`, mã `109`, kèm header `Retry-After`).

## Trong POS Apps

App chạy trong POS không dùng API key: POS cấp app token theo đúng người đang dùng. Xem [POS Apps › Truy cập dữ liệu](/developers/apps/data-access).