API quản lý khoá
Máy chủ cửa hàng của bạn tạo khoá khi có đơn, thu hồi, gia hạn, đổi máy và tra cứu khoá bằng API key lrs_ với scope license:read và license:write.
https://api.lrsvn.com/v1/license/apps/{id}/keysGốc là https://api.lrsvn.com/v1/license/…, xác thực bằng Authorization: Bearer lrs_… như mọi API của tổ chức — xem Xác thực & API key. Chỉ gọi từ máy chủ của bạn; API key không bao giờ nằm trong phần mềm giao cho khách.
Quyền
| Cách gọi | Đọc | Ghi |
|---|---|---|
| API key | scope license:read | scope license:write |
| Phiên đăng nhập (dashboard) | Owner, Admin, Member | Owner, Admin |
- Xuất CSV mọi khoá đầy đủ: Owner/Admin, hoặc API key có
license:write. - Chỉ phiên đăng nhập, API key nhận
403 user_session_required: bật dịch vụ, xoay khoá ký, ngừng khoá ký cũ, xoá ứng dụng. - Tổ chức chưa bật LR License:
403 license_not_enabled. Tài khoản bị LRS tạm khoá: vẫn đọc được, mọi thao tác ghi trả423 license_suspended.
Mọi yêu cầu ghi (POST, PATCH, DELETE) cần header Idempotency-Key dài 8–128 ký tự — dùng mã đơn hàng để gửi lại không tạo khoá trùng. Xem Giới hạn tần suất.
Yêu cầu
Tạo khoá cho một đơn hàng:
curl -X POST https://api.lrsvn.com/v1/license/apps/lapp_8kq2m7x4c1/keys \
-H "Authorization: Bearer $LRS_API_KEY" \
-H "Idempotency-Key: order-1042-keys" \
-H "Content-Type: application/json" \
-d '{ "count": 1, "level": 2, "duration": { "value": 30, "unit": "day" }, "max_devices": 1, "note": "Đơn #1042" }'Tham số
| Tham số | Kiểu | Mô tả |
|---|---|---|
| count | number | 1–100 khoá mỗi lần, mặc định 1. |
| level | number | Gói quyền có trong ứng dụng, mặc định gói đầu tiên. |
| duration | object | Thời hạn { "value", "unit" }, unit là minute, hour hoặc day: 1 phút – 36.500 ngày, tính từ lần kích hoạt đầu (khoá chưa dùng không bị trừ thời gian). |
| duration_seconds | number | Cùng thời hạn tính bằng giây, 60 – 3.153.600.000. |
| duration_days | number | Cũ (vẫn nhận): 1–36.500 ngày. Nên dùng duration. |
| expires_at | string | Ngày hết hạn cố định (RFC 3339, ở tương lai). Chỉ gửi một trong duration, duration_seconds, duration_days, expires_at; bỏ cả bốn là khoá vĩnh viễn. |
| max_devices | number | 1–100 thiết bị, mặc định 1 (chỉ có tác dụng khi ràng buộc hwid). |
| binding | string | Ghi đè cách ràng buộc của ứng dụng: hwid, none, hoặc null/bỏ trống = theo ứng dụng. |
| max_concurrent_sessions | number | Ghi đè số phiên cùng lúc: 0 (không giới hạn) – 1.000, hoặc null/bỏ trống = theo ứng dụng. |
| note | string | Ghi chú tối đa 200 ký tự (ví dụ mã đơn) — tìm lại được bằng ?q=. |
| key | string | Khoá tự đặt, chỉ khi count = 1: tối đa 64 ký tự [A-Za-z0-9_-], ít nhất 12 chữ hoặc số. Bỏ trống thì LRS sinh khoá dạng TIỀNTỐ-XXXX-XXXX-XXXX-XXXX. |
| files | string[] | Id tệp (lfil_…, tối đa 100) gắn với mọi khoá tạo lần này — khoá tải được các tệp phạm vi "Chỉ khoá được gắn" này. Id không thuộc ứng dụng hoặc đã xoá → 422 fields.files. Xem Tệp tải về. |
Phản hồi
HTTP/1.1 201 Created
{
"data": [
{
"id": "lkey_9d2m4q7x1c",
"key": "LRK-7F3K-9QXA-M2D8-T5WN",
"key_last4": "T5WN",
"level": 2,
"level_name": "VIP",
"duration_seconds": 2592000,
"duration": { "value": 30, "unit": "day" },
"duration_days": 30,
"expires_at": null,
"max_devices": 1,
"devices": 0,
"binding": "hwid",
"binding_override": null,
"max_concurrent_sessions": 1,
"max_sessions_override": null,
"sessions": 0,
"status": "unused",
"revoked_reason": null,
"note": "Đơn #1042",
"first_activated_at": null,
"last_seen_at": null,
"last_reset_at": null,
"created_by": { "type": "api_key", "name": "Cửa hàng" },
"created_at": "2026-10-24T03:15:00Z",
"updated_at": "2026-10-24T03:15:00Z",
"files": []
}
]
}duration_seconds là thời hạn tính từ lần kích hoạt đầu (null cùng expires_at: null = vĩnh viễn); duration là thời hạn đó theo đơn vị lớn nhất chia hết (7.200 giây → { "value": 2, "unit": "hour" }); duration_days (cũ) chỉ có khi thời hạn là số ngày tròn, còn lại null. Lần kích hoạt đầu đặt expires_at = lúc đó + thời hạn.
binding và max_concurrent_sessions là giá trị đang áp (đã tính ghi đè); binding_override, max_sessions_override là ghi đè của khoá (null = theo ứng dụng); sessions là số phiên đang sống; files là các tệp gắn với khoá [{ id, name, scope }] (danh sách, chi tiết và phản hồi tạo đều có).
key đầy đủ chỉ có trong phản hồi tạo khoá. Danh sách và chi tiết luôn trả key: null kèm key_last4; cần xem lại thì gọi …/reveal. status là unused, active, expired hoặc revoked.
Các endpoint khác
| Endpoint | Việc |
|---|---|
| GET /license/apps | Scope license:read. Danh sách ứng dụng của tổ chức ({ data }). |
| PATCH /license/apps/{id} | Scope license:write. Sửa ứng dụng, gồm binding (hwid / none), max_concurrent_sessions (0 = không giới hạn), session_overflow (reject / kick_oldest), heartbeat_timeout_seconds (30–600), update_file_id (tệp mà update_required dẫn tới, null = không dùng); gửi kèm expected_updated_at (409 license_app_changed nếu người khác vừa sửa). |
| GET /license/apps/{id}/files | Scope license:read. Tệp tải về và dung lượng của tổ chức — tải bản lên, đổi bản hiện hành, lượt tải: xem Tệp tải về. |
| GET /license/apps/{id}/keys | Scope license:read. Danh sách khoá, phân trang { data, meta: { total, page, limit } }. Lọc status, level, q (ghi chú hoặc 4 ký tự cuối), file_id (khoá gắn với tệp đó), page, limit ≤ 100. |
| GET /license/apps/{id}/keys?key=LRK-… | Scope license:read. Tra đúng một khoá theo giá trị đầy đủ (không phân biệt hoa thường, bỏ qua dấu gạch). |
| GET /license/apps/{id}/keys/{keyId} | Scope license:read. Chi tiết khoá kèm device_list, live_sessions (phiên đang sống: id, device_id, hwid, ip, version, created_at, last_seen_at, expires_at) và api_reset_available_at. |
| GET /license/apps/{id}/keys/{keyId}/reveal | Scope license:read. { id, key } — khoá đầy đủ, Cache-Control: no-store, ghi nhật ký kiểm toán kèm IP, tối đa 30 lần/phút mỗi người hoặc API key. |
| PATCH /license/apps/{id}/keys/{keyId} | Scope license:write. Sửa level, max_devices, note, expires_at (null = bỏ ngày hết hạn), binding, max_concurrent_sessions (null = theo ứng dụng), files (thay cả tập tệp gắn: [] gỡ hết, bỏ trống = giữ nguyên). |
| POST /license/apps/{id}/keys/{keyId}/revoke | Scope license:write. Thu hồi, { "reason": "…" } tối đa 200 ký tự; mọi phiên của khoá kết thúc ngay. |
| POST /license/apps/{id}/keys/{keyId}/restore | Scope license:write. Khôi phục khoá đã thu hồi. |
| POST /license/apps/{id}/keys/{keyId}/extend | Scope license:write. Gia hạn { "value": 2, "unit": "hour" }, { "seconds": 7200 } hoặc { "days": 30 } (cũ) — 1 phút – 36.500 ngày, tính từ lúc muộn hơn giữa bây giờ và ngày hết hạn hiện tại; khoá chưa kích hoạt thì thời hạn dài thêm (tối đa 36.500 ngày). |
| POST /license/apps/{id}/keys/{keyId}/reset-devices | Scope license:write. Đổi máy: gỡ mọi thiết bị và đóng phiên. Qua API key phải chờ reset_cooldown_hours của ứng dụng giữa hai lần. |
| DELETE /license/apps/{id}/keys/{keyId}/devices/{deviceId} | Scope license:write. Gỡ một thiết bị. Qua API key cũng tính là một lần đổi máy (cùng thời gian chờ). |
| DELETE /license/apps/{id}/keys/{keyId} | Scope license:write. Xoá khoá (204). |
| DELETE /license/apps/{id}/sessions/{sessionId} | Scope license:write. Kết thúc một phiên (204, ghi nhật ký kiểm toán); phần mềm nhận session_revoked ở lần heartbeat/check kế tiếp. |
| GET /license/apps/{id}/keys/export | Scope license:write. CSV mọi khoá đầy đủ khớp bộ lọc (tối đa 50.000 dòng; cột key, level, status, duration_seconds, duration, expires_at, max_devices, devices, note, created_at — duration dạng 2 hour), ghi nhật ký kiểm toán. |
Các thao tác trên một khoá trả lại chi tiết khoá sau khi đổi. Danh sách phiên, danh sách chặn, nhật ký và thống kê cũng có endpoint dưới /license/apps/{id}/… (sessions, blocks, events, stats).
Ví dụ nút "Đổi máy" trong trang tài khoản của cửa hàng:
curl -X POST https://api.lrsvn.com/v1/license/apps/lapp_8kq2m7x4c1/keys/lkey_9d2m4q7x1c/reset-devices \
-H "Authorization: Bearer $LRS_API_KEY" \
-H "Idempotency-Key: reset-lkey_9d2m4q7x1c-2026-10-24"Mã lỗi
| HTTP | Mã | Khi nào |
|---|---|---|
| 400 | invalid_json | JSON hỏng, có trường lạ hoặc sai kiểu. |
| 403 | license_not_enabled | Tổ chức chưa bật LR License. |
| 403 | scope_denied | API key thiếu license:read / license:write. |
| 403 | user_session_required | Thao tác chỉ làm được trong dashboard (bật dịch vụ, khoá ký, xoá ứng dụng). |
| 403 | forbidden | Vai trò không đủ (ví dụ Member xuất CSV). |
| 404 | license_app_not_found | Ứng dụng không có hoặc thuộc tổ chức khác. |
| 404 | license_key_not_found | Khoá không có trong ứng dụng. |
| 404 | license_device_not_found | Thiết bị không thuộc khoá hoặc đã được gỡ. |
| 409 | license_limit_keys | Vượt số khoá tối đa của tổ chức. |
| 409 | license_limit_apps | Vượt số ứng dụng tối đa của tổ chức. |
| 409 | license_key_exists | Khoá tự đặt đã có trong ứng dụng. |
| 409 | license_key_revoked | Thu hồi khoá đã bị thu hồi. |
| 409 | license_key_not_revoked | Khôi phục khoá chưa bị thu hồi. |
| 409 | license_key_lifetime | Gia hạn khoá vĩnh viễn. |
| 409 | idempotency_conflict | Cùng Idempotency-Key nhưng nội dung khác. |
| 422 | validation_error | Sai dữ liệu; fields nêu trường lỗi (kể cả thiếu Idempotency-Key). |
| 423 | license_suspended | Tài khoản LR License đang bị LRS tạm khoá. |
| 429 | license_reset_cooldown | Đổi máy qua API key trước khi hết thời gian chờ; xem Retry-After. |
| 429 | rate_limited | Vượt giới hạn (cổng API, hoặc 30 lần xem khoá mỗi phút). |
{
"code": "validation_error",
"message": "Vui lòng kiểm tra thông tin đã nhập.",
"fields": { "count": "Số lượng từ 1 đến 100 khoá mỗi lần." },
"request_id": "req_4f9c2a7e"
}