Get Active Signing Credential

Lists a device's ACTIVE signing credentials — for example to decide which key to revoke with Revoke Signing Credential. It is a backend lookup: the SDK's getStatus only reports the key stored on the device and never calls it.

Endpoint

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

{
  "device_id": "device_00000001"
}

Parameters:

Param	Type	Required	Default	Description
device_id	string	Yes	—	The device ID sent to Init. Must not be blank, must not start or end with whitespace, and must be at most 128 characters.

Returns: GetActiveSigningCredentialResponse

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

Field	Type	Description
data.request_id	string	The request ID, used for tracing.
data.credentials	array	The device's ACTIVE credentials, newest first. Empty when the device has none. A device can hold several, because earlier keys stay ACTIVE until revoked.
data.credentials[].key_id	string	Signing key ID (UUID) — the value the SDK sends in X-Device-Key-Id.
data.credentials[].status	string	Always ACTIVE in this response.
data.credentials[].key_attestation	string	How the key is protected: STRONGBOX or TEE (Android, verified), SECURE_ENCLAVE (iOS), or NONE (Android, could not be verified).
data.credentials[].created_at	string	Registration time (RFC 3339).
data.credentials[].metadata	object	Device information recorded at Confirm from the Device-Model, Os-Version, Platform and Sdk-Version headers. The key is absent when no metadata was recorded; it is never null. When present, all four fields are returned, and a header that was not sent is "".
data.credentials[].metadata.device_model	string	Device model.
data.credentials[].metadata.os_version	string	OS version.
data.credentials[].metadata.platform	string	The Platform header as sent (trimmed), e.g. android; not normalised.
data.credentials[].metadata.sdk_version	string	FaceAuthen SDK version.
errors	array	Detail of each failure. Empty on success.

An empty credentials array is a successful lookup, not an error.

WARNING

Call this endpoint from your backend only, with your Access Key. The SDK's Bearer token is rejected with 403101.

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.
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

• Init Signing Credential — register a key for a device
• Revoke Signing Credential — revoke a key that should no longer work