Xác thực API Key

Tổng quan

Các request tới public API của NiceQR.me được xác thực bằng API key gửi trong header X-Api-Key.

Trong UI sản phẩm, bạn quản lý các credential này tại Dashboard > API Keys.

Bộ tài liệu này cố ý không mô tả các flow JWT của người dùng như đăng ký, đăng nhập, Google login, refresh token hoặc các endpoint chỉ dành cho dashboard.

Tạo API Key

API key được tạo và quản lý từ Dashboard > API Keys.

API Keys là tính năng của gói Business.
Việc tạo và quản lý API key không được public qua REST endpoint.
Raw key chỉ hiển thị đúng một lần. Hãy lưu lại ngay vì sau đó hệ thống sẽ không hiển thị lại.

Môi trường

Trong Dashboard > API Keys, trường Environment dùng các giá trị sau:

Live → key bắt đầu bằng nq_live_...
Test → key bắt đầu bằng nq_test_...

Request Header

X-Api-Key: nq_live_your_api_key

Quyền

Với endpoint public hiện đang được tài liệu hóa, hãy bật quyền Generate QR Code (qr:generate) trong Dashboard > API Keys.

Trạng thái key

Trong Dashboard > API Keys, một key có thể ở các trạng thái:

Active
Suspended
Revoked
Expired

Route public được tài liệu hóa chỉ hoạt động khi key thực sự còn active và tài khoản vẫn có gói Business đang hiệu lực.

Nếu key hợp lệ nhưng không có đúng quyền yêu cầu, request sẽ bị ẩn có chủ đích và trả về 404 Not Found với body rỗng.

Hành vi khi thất bại

Với public route dùng API key, backend cố ý trả về 404 Not Found với body rỗng khi:

thiếu header X-Api-Key
key không hợp lệ
key đã bị revoke hoặc hết hạn
key bị suspended vì tài khoản không còn Business plan đang hoạt động
key không có đúng quyền cần thiết

Ở phía client, hãy xem response đó như một lỗi xác thực hoặc phân quyền.

Ví dụ

curl -X POST https://api.niceqr.me/v1/qr/generate \
  -H "X-Api-Key: nq_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "data": "https://example.com",
    "bodyStyle": "square",
    "bodyBrush": { "type": "Solid", "color": "#000000" }
  }'

Ghi chú bảo mật

Không nhúng Live API key vào frontend hoặc code chạy trên trình duyệt.
Chỉ dùng API key cho các tích hợp server-to-server.
Nếu key bị lộ, hãy revoke và tạo key mới từ dashboard.

On this page