Xác nhận khóa ký
Hoàn tất việc đăng ký khóa đã bắt đầu bằng Khởi tạo khóa ký. Backend của bạn gửi bằng chứng đăng ký (registration proof) do hàm createRegistrationProof của SDK tạo ra; khi thành công, khóa trên thiết bị trở thành một khóa ký (signing credential) ở trạng thái ACTIVE của thiết bị, và response — kết quả đăng ký (registration result) — được chuyển lại cho hàm activateCredential của SDK.
Endpoint
POST /v1/signing-credential/confirm
Content-Type: application/json
Device-Model: Pixel 8
Os-Version: 15
Platform: android
Sdk-Version: 1.4.0{
"device_id": "device_00000001",
"key_id": "<KEY_ID>",
"proof": "<REGISTRATION_PROOF>"
}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. Cùng quy tắc: không để trống, không có khoảng trắng ở đầu hoặc cuối, dài tối đa 128 ký tự. |
key_id | string | Có | — | key_id do Init trả về. |
proof | string | Có | — | Chuỗi JWS dạng compact do hàm createRegistrationProof của SDK trả về. Chuyển nguyên vẹn. |
Header:
Ngoài các header xác thực, hãy gửi thông tin thiết bị mà SDK báo cáo. Các giá trị được cắt khoảng trắng và lưu cùng khóa ký dưới dạng metadata mang tính thông tin, được Lấy khóa ký đang hoạt động trả về. Giá trị được lưu đúng như khi gửi, không được chuẩn hóa.
| Header | Bắt buộc | Mô tả |
|---|---|---|
Device-Model | Không | Dòng máy, ví dụ Pixel 8. |
Os-Version | Không | Phiên bản hệ điều hành, ví dụ 15. |
Platform | Không | ios hoặc android (không phân biệt hoa thường). Đồng thời quyết định cách gắn nhãn attestation của khóa. |
Sdk-Version | Không | Phiên bản SDK FaceAuthen, ví dụ 1.4.0. |
Trả về: ConfirmSigningCredentialResponse
Hãy gọi endpoint này trước thời điểm expires_at do Init trả về. Trên Android, bằng chứng mang theo chuỗi attestation của khóa; nếu chuỗi này bị thiếu hoặc không xác minh được, lần gọi vẫn không thất bại — khóa ký được lưu với key_attestation: NONE.
Ví dụ request
curl --location '<BASE_URL>/v1/signing-credential/confirm' \
--header 'Authorization: ATV <ACCESS_ID>:<SIGNATURE>' \
--header 'X-TV-Timestamp: <TIMESTAMP>' \
--header 'Content-Type: application/json' \
--header 'Device-Model: Pixel 8' \
--header 'Os-Version: 15' \
--header 'Platform: android' \
--header 'Sdk-Version: 1.4.0' \
--data '{
"device_id": "device_00000001",
"key_id": "<KEY_ID>",
"proof": "<REGISTRATION_PROOF>"
}'Response
{
"success": true,
"code": 0,
"message": "Success",
"data": {
"request_id": "f48085e4-3ae4-40bb-b0e1-9b2c72575bc1",
"key_id": "<KEY_ID>",
"key_thumbprint": "NzbLsXh8uDCcd-6MNwXF4W_7noWXFZAfHkxZsRGC9Xs",
"status": "ACTIVE"
},
"errors": []
}| Trường | Kiểu | Mô tả |
|---|---|---|
data.request_id | string | ID của request, dùng để truy vết. |
data.key_id | string | ID của khóa đã được xác nhận — chính là key_id từ Init. SDK gửi ID này trong X-Device-Key-Id. |
data.key_thumbprint | string | Thumbprint RFC 7638 của public key đã đăng ký. |
data.status | string | ACTIVE ở lần xác nhận đầu tiên; trạng thái hiện tại của khóa ký khi gọi lại. |
errors | array | Chi tiết từng lỗi. Rỗng khi thành công. |
Chuyển key_id, key_thumbprint và status cho SDK làm kết quả đăng ký mà không thay đổi bất kỳ giá trị nào.
- Gọi lại an toàn. Gọi lại cho một lần đăng ký đã được xác nhận sẽ trả về kết quả ban đầu và không bao giờ tạo khóa ký thứ hai.
- Mỗi lần xác nhận thêm một khóa. Một thiết bị có thể giữ không giới hạn số khóa ACTIVE: mỗi lần Confirm thành công thêm một khóa mới, và các khóa trước đó vẫn ACTIVE cho đến khi bạn thu hồi (revoke) chúng bằng Thu hồi khóa ký.
- Một lần gọi thất bại giữ nguyên các khóa hiện có của thiết bị.
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. |
2009000 | Không tìm thấy lần đăng ký hoặc lần đăng ký đã hết hạn. |
2009001 | Bằng chứng đăng ký không hợp lệ. |
2009003 | Một lần đăng ký khác cho khóa này đang được xử lý. Vui lòng thử lại. |
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. |
registration_expired | key_id không tồn tại, thuộc về thiết bị khác, hoặc đã quá expires_at. Hãy bắt đầu lại bằng Init. |
registration_proof_invalid | Bằng chứng không vượt qua một bước kiểm tra. detail.reason cho biết bước đó, ví dụ proof_signature_invalid, proof_challenge_mismatch, key_already_registered. |
registration_conflict | Một lần xác nhận đồng thời cho cùng key_id đang chạy. Có thể thử lại an toà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; hoặc thiếu key_id hay proof. |
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 — liệt kê các khóa ACTIVE của thiết bị
- Thu hồi khóa ký — thu hồi khóa khi mất điện thoại