Thu hồi khóa ký

Thu hồi (revoke) các khóa ký (signing credential) của một thiết bị — ví dụ khi người dùng báo mất hoặc bị đánh cắp điện thoại, hoặc khi bạn phát hiện gian lận. Một khóa đã bị thu hồi không bao giờ được kích hoạt lại; để ký lại, thiết bị đăng ký khóa mới bằng Khởi tạo khóa ký và Xác nhận khóa ký.

Khóa ký thuộc về thiết bị, không thuộc về người dùng FaceAuthen: việc xóa hồ sơ (profile) khuôn mặt bằng Xóa Face Authen không thu hồi khóa nào. Hãy gọi endpoint này khi các khóa của một thiết bị cần ngừng hoạt động.

Endpoint

POST /v1/signing-credential/revoke
Content-Type: application/json

{
  "device_id": "device_00000001",
  "key_id": "<KEY_ID>"
}

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ự.
key_id	string	Không	—	Khóa cần thu hồi. Bỏ trống để thu hồi toàn bộ khóa ACTIVE của thiết bị ("mất điện thoại").

Trả về: RevokeSigningCredentialResponse

Ví dụ request

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

Response

{
  "success": true,
  "code": 0,
  "message": "Success",
  "data": {
    "request_id": "cfc7b8d5-f2e2-437b-80e5-d600dfad26e2",
    "revoked": [
      {
        "key_id": "<KEY_ID>",
        "status": "REVOKED",
        "revoked_at": "2026-09-30T02:10:00Z"
      }
    ]
  },
  "errors": []
}

Trường	Kiểu	Mô tả
data.request_id	string	ID của request, dùng để truy vết.
data.revoked	array	Các khóa bị thu hồi trong lần gọi này. Rỗng khi không có khóa ACTIVE nào để thu hồi.
data.revoked[].key_id	string	ID của khóa ký (UUID).
data.revoked[].status	string	Luôn là REVOKED.
data.revoked[].revoked_at	string	Thời điểm thu hồi (RFC 3339).
errors	array	Chi tiết từng lỗi. Rỗng khi thành công.

• Idempotent. Thu hồi một khóa đã bị thu hồi hoặc đã hết hạn vẫn thành công, với mảng revoked rỗng.
• Một key_id không thuộc về device_id trong tenant của bạn trả về signing_credential_not_found.

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.
2009004	Không tìm thấy khóa ký.
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.
signing_credential_not_found	key_id không tồn tại cho thiết bị này trong tenant của bạn.
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

• Lấy khóa ký đang hoạt động — xác nhận không còn khóa ACTIVE nào
• Khởi tạo khóa ký — đăng ký khóa mới trên điện thoại mới