Khởi tạo khóa ký

Bắt đầu đăng ký một khóa ký trên thiết bị (device signing key) cho một thiết bị. Khóa ký (signing credential) thuộc về thiết bị, không thuộc về người dùng FaceAuthen, nên không cần hồ sơ (profile) khuôn mặt. Backend của bạn gọi endpoint này cho một thiết bị của người dùng đã được xác thực trong phiên của chính bạn, và nhận về một challenge dùng một lần — ngữ cảnh đăng ký (registration context) — để ứng dụng chuyển cho Mobile SDK tạo khóa và ký challenge đó.

Việc đăng ký một khóa gồm hai lần gọi từ backend của bạn, với SDK ở giữa:

1. Init (endpoint này) trả về ngữ cảnh đăng ký.
2. Ứng dụng của bạn chuyển nguyên vẹn ngữ cảnh này cho hàm createRegistrationProof của SDK. Hàm này tạo một khóa được bảo vệ bằng phần cứng (Android Keystore / iOS Secure Enclave) và trả về một bằng chứng đăng ký (registration proof).
3. Xác nhận khóa ký gửi lại bằng chứng này và kích hoạt khóa.
4. Ứng dụng của bạn chuyển nguyên vẹn kết quả của Confirm cho hàm activateCredential của SDK.

INFO

Việc xác minh signature của thiết bị trên các request từ SDK được bật cho từng tenant. Trên tenant chưa bật, khóa đã đăng ký được lưu lại nhưng chưa bắt buộc. Xem Ký request để biết các header mà SDK gửi khi việc xác minh đã được bật.

Endpoint

POST /v1/signing-credential/init
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. 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ự. Được lưu đúng như khi gửi, không bị cắt khoảng trắng. SDK gửi cùng giá trị này trong header Device-Id của các request đã ký.

Trả về: InitSigningCredentialResponse

Ví dụ request

curl --location '<BASE_URL>/v1/signing-credential/init' \
  --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": "cfc7b8d5-f2e2-437b-80e5-d600dfad26e2",
    "device_id": "device_00000001",
    "key_id": "<KEY_ID>",
    "challenge": "c2lnbmluZy1jaGFsbGVuZ2UtZXhhbXBsZQ",
    "expires_at": 1789697400,
    "audience": "<AUDIENCE>"
  },
  "errors": []
}

Trường	Kiểu	Mô tả
data.request_id	string	ID của request, dùng để truy vết.
data.device_id	string	Thiết bị mà việc đăng ký được bắt đầu cho — lặp lại giá trị trong request.
data.key_id	string	ID của khóa ký (UUID). Gửi lại ID này cho Confirm; sau khi xác nhận, SDK gửi ID này trong X-Device-Key-Id.
data.challenge	string	Challenge dùng một lần mà SDK sẽ ký.
data.expires_at	integer	Hạn chót để gọi Confirm, tính bằng giây epoch UTC.
data.audience	string	Audience mà SDK ghi vào bằng chứng.
errors	array	Chi tiết từng lỗi. Rỗng khi thành công.

Chuyển key_id, challenge, expires_at và audience cho SDK làm ngữ cảnh đăng ký mà không thay đổi bất kỳ giá trị nào. Giữ device_id và key_id ở backend của bạn — Confirm cần cả hai.

WARNING

Chỉ gọi endpoint này từ backend của bạn, bằng Access Key, và chỉ cho một thiết bị của người dùng đã được xác thực trong phiên của chính bạn. Token giao dịch của SDK (Authorization: Bearer …) bị từ chối với mã 403101. Hãy giữ kênh kết nối giữa ứng dụng và backend của bạn an toàn: kẻ tấn công có thể thay thế ngữ cảnh đăng ký, bằng chứng hoặc kết quả trên đường truyền sẽ gắn được khóa của chính họ vào thiết bị đó. Hãy xác nhận mọi kết quả xác thực từ backend của bạn bằng Xác minh khóa xác thực giao dịch — không bao giờ hành động dựa trên kết quả mà ứng dụng báo về.

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. detail.reason cho biết bước kiểm tra: Empty device id., Device id exceeds 128 characters. hoặc Device id must not start or end with whitespace.
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

• Xác nhận khóa ký — kích hoạt khóa bằng bằng chứng đăng ký từ SDK
• Lấy khóa ký đang hoạt động — liệt kê các khóa mà thiết bị đã có