Lấy khóa ký đang hoạt động

Liệt kê các khóa ký (signing credential) ở trạng thái ACTIVE của một thiết bị — ví dụ để quyết định thu hồi khóa nào bằng Thu hồi khóa ký. Đây là một lần tra cứu phía backend: hàm getStatus của SDK chỉ báo cáo khóa được lưu trên thiết bị và không bao giờ gọi endpoint này.

Endpoint

POST /v1/signing-credential/get-active
Content-Type: application/json

{
  "device_id": "device_00000001"
}

Tham số:

Tham số	Kiểu	Bắt buộc	Mặc định	Mô tả
device_id	string	Có	—	Device ID đã gửi cho Init. Không được để trống, không được bắt đầu hoặc kết thúc bằng khoảng trắng, và dài tối đa 128 ký tự.

Trả về: GetActiveSigningCredentialResponse

Ví dụ request

curl --location '<BASE_URL>/v1/signing-credential/get-active' \
  --header 'Authorization: ATV <ACCESS_ID>:<SIGNATURE>' \
  --header 'X-TV-Timestamp: <TIMESTAMP>' \
  --header 'Content-Type: application/json' \
  --data '{
    "device_id": "device_00000001"
  }'

Response

{
  "success": true,
  "code": 0,
  "message": "Success",
  "data": {
    "request_id": "9a7c1e52-0d4b-4f3a-8c6e-2b1f0e9d8c7a",
    "credentials": [
      {
        "key_id": "<KEY_ID>",
        "status": "ACTIVE",
        "key_attestation": "TEE",
        "created_at": "2026-09-30T02:00:00Z",
        "metadata": {
          "device_model": "Pixel 8",
          "os_version": "15",
          "platform": "android",
          "sdk_version": "1.4.0"
        }
      }
    ]
  },
  "errors": []
}

Trường	Kiểu	Mô tả
data.request_id	string	ID của request, dùng để truy vết.
data.credentials	array	Các khóa ký ACTIVE của thiết bị, mới nhất trước. Rỗng khi thiết bị chưa có khóa nào. Một thiết bị có thể giữ nhiều khóa, vì các khóa trước đó vẫn ACTIVE cho đến khi bị thu hồi.
data.credentials[].key_id	string	ID của khóa ký (UUID) — giá trị SDK gửi trong X-Device-Key-Id.
data.credentials[].status	string	Luôn là ACTIVE trong response này.
data.credentials[].key_attestation	string	Cách khóa được bảo vệ: STRONGBOX hoặc TEE (Android, đã xác minh), SECURE_ENCLAVE (iOS), hoặc NONE (Android, không xác minh được).
data.credentials[].created_at	string	Thời điểm đăng ký (RFC 3339).
data.credentials[].metadata	object	Thông tin thiết bị được ghi nhận lúc Confirm từ các header Device-Model, Os-Version, Platform và Sdk-Version. Key này không xuất hiện khi không có metadata nào được ghi nhận; nó không bao giờ là null. Khi có, cả bốn trường đều được trả về, và một header không được gửi có giá trị "".
data.credentials[].metadata.device_model	string	Dòng máy.
data.credentials[].metadata.os_version	string	Phiên bản hệ điều hành.
data.credentials[].metadata.platform	string	Header Platform đúng như khi gửi (đã cắt khoảng trắng), ví dụ android; không được chuẩn hóa.
data.credentials[].metadata.sdk_version	string	Phiên bản SDK FaceAuthen.
errors	array	Chi tiết từng lỗi. Rỗng khi thành công.

Mảng credentials rỗng là một lần tra cứu thành công, không phải lỗi.

WARNING

Chỉ gọi endpoint này từ backend của bạn, bằng Access Key. Bearer token của SDK bị từ chối với mã 403101.

Lỗi

Mã	Thông báo
2001010	Không tìm thấy Access ID trong hệ thống.
401100	Hành động không được phép. Bạn không có quyền thực hiện hành động này.
403101	Từ chối quyền truy cập. Bạn không có quyền thực hiện hành động này.
4001000	Tham số đầu vào vi phạm một ràng buộc.
4001001	Header X-TV-Timestamp đã hết hạn. Vui lòng cung cấp timestamp mới hơn.
5001000	Xảy ra lỗi không mong đợi trong quá trình xử lý request.

Mã	Mô tả
access_id_not_found	Không tìm thấy Access ID trong hệ thống.
access_denied_exception	Thiếu hoặc sai Access Key hoặc signature.
permission_denied_exception	Gọi bằng Bearer token của SDK; chỉ Access Key được chấp nhận.
invalid_parameter_exception	device_id bị thiếu, để trống, dài hơn 128 ký tự, hoặc bắt đầu hay kết thúc bằng khoảng trắng.
request_time_too_skewed	Header X-TV-Timestamp đã hết hạn, cần một cái mới hơn.
internal_server_error	Xảy ra lỗi không mong đợi trong quá trình xử lý request.

Bước tiếp theo

• Khởi tạo khóa ký — đăng ký khóa cho một thiết bị
• Thu hồi khóa ký — thu hồi khóa không còn được phép hoạt động