Init Signing Credential

Starts registering a device signing key for a device. A signing credential belongs to the device, not to a FaceAuthen user, so no face profile is needed. Your backend calls it for a device of the user authenticated in your own session, and gets back a single-use challenge — the registration context — that the app passes to the Mobile SDK to create the key and sign the challenge.

Registering a key takes two calls from your backend, with the SDK in between:

1. Init (this endpoint) returns the registration context.
2. Your app passes it unchanged to the SDK's createRegistrationProof, which generates a hardware-backed key (Android Keystore / iOS Secure Enclave) and returns a registration proof.
3. Confirm Signing Credential sends the proof back and activates the key.
4. Your app passes Confirm's result unchanged to the SDK's activateCredential.

INFO

Device-signature verification on SDK requests is enabled tenant by tenant. On a tenant where it is not enabled, a registered key is stored but not required. See Request Signing for the headers the SDK sends once it is.

Endpoint

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

{
  "device_id": "device_00000001"
}

Parameters:

Param	Type	Required	Default	Description
device_id	string	Yes	—	The device ID. Must not be blank, must not start or end with whitespace, and must be at most 128 characters. Stored exactly as sent, not trimmed. The SDK sends the same value in the Device-Id header of its signed requests.

Returns: InitSigningCredentialResponse

Sample 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": []
}

Field	Type	Description
data.request_id	string	The request ID, used for tracing.
data.device_id	string	The device the registration was started for — echoes the request.
data.key_id	string	The signing key's ID (UUID). Send it back to Confirm; once confirmed, the SDK sends it in X-Device-Key-Id.
data.challenge	string	Single-use challenge the SDK signs.
data.expires_at	integer	Deadline to call Confirm, as UTC epoch seconds.
data.audience	string	Audience the SDK writes into the proof.
errors	array	Detail of each failure. Empty on success.

Forward key_id, challenge, expires_at and audience to the SDK as the registration context without changing any value. Keep device_id and key_id on your backend — Confirm needs both.

WARNING

Call this endpoint from your backend only, with your Access Key, and only for a device of the user authenticated in your own session. The SDK's transaction token (Authorization: Bearer …) is rejected with 403101. Keep the channel between your app and your backend secure: an attacker who can replace the registration context, the proof or the result in transit can bind their own key to that device. Confirm every authentication outcome from your backend with Verify Transaction Authentication Key — never act on the result the app reports.

Errors

Code	Message
2001010	Access ID not found in the system.
401100	Unauthorized action. You do not have permission to perform this action.
403101	Permission denied. You do not have permission to perform this action.
4001000	Input parameter violates a constraint.
4001001	The X-TV-Timestamp header is expired. Please provide a newer timestamp.
5001000	Some unexpected error occurs while processing the request.

Code	Description
access_id_not_found	Access ID not found in the system.
access_denied_exception	Missing or invalid Access Key or signature.
permission_denied_exception	Called with an SDK Bearer token; only the Access Key is allowed.
invalid_parameter_exception	device_id is missing, blank, longer than 128 characters, or starts or ends with whitespace. detail.reason names the check: Empty device id., Device id exceeds 128 characters. or Device id must not start or end with whitespace.
request_time_too_skewed	The X-TV-Timestamp header is expired, need a newer one.
internal_server_error	Some unexpected error occurs while processing the request.

Next Steps

• Confirm Signing Credential — activate the key with the SDK's registration proof
• Get Active Signing Credential — list the keys the device already has