Verify Face Authen

Authenticates a user against their registered face profile and returns matched, unmatched or unsure with a score. When a transaction ref_id is supplied it also mints the authentication_key your backend redeems to close the transaction.

Endpoint

POST /v1/face_auth
Content-Type: application/json

{
  "user_id": "user_00000001",
  "ref_id": "ref_00000001",
  "faces": [
    { "id": "a4facba3-334b-41fb-97e3-4766cb70ae29" }
  ],
  "device_id": "device_00000001",
  "app_id": "app_00000001",
  "lat": "10.7769",
  "lng": "106.7009",
  "face_type": "selfie",
  "metadata": { "key2": "value2" }
}

Parameters:

Param	Type	Required	Default	Description
user_id	string	Yes	—	User ID of the customer.
ref_id	string	No	—	Reference ID of a transaction created before verification. Supply it so the transaction can be looked up afterwards for its status.
faces	ImageData[]	Yes	—	Images of the user's selfie. At least one is required.
device_id	string	No	—	The user's device ID, shown in face auth history on the admin portal.
app_id	string	No	—	The app the customer used, shown in face auth history.
lat	string	No	—	Latitude of the device used.
lng	string	No	—	Longitude of the device used.
face_type	string	No	selfie	Type of face input: selfie or id_card.
metadata	json_object	No	—	Any key-value metadata to store with this login.

ImageData

Param	Type	Required	Default	Description
id	string	No	—	ID of the image returned by Upload Image.
base64	string	No	—	Base64-encoded text of the image data.
label	string	No	—	Label of the image, as described in Usage Recommendations.
metadata	string_json	No	—	Key/value JSON string. Example: {"gesture":"left","type":1}

Returns: VerifyFaceAuthResponse

Sample Request

curl -X POST \
  '<BASE_URL>/v1/face_auth' \
  -H 'Authorization: ATV <ACCESS_ID>:<SIGNATURE>' \
  -H 'X-TV-Timestamp: <TIMESTAMP>' \
  -H 'Content-Type: application/json' \
  -d '{
    "user_id": "user_00000001",
    "faces": [
      { "id": "a4facba3-334b-41fb-97e3-4766cb70ae29" },
      { "id": "c5a2a405-f152-4248-b746-3af76b241ef7" },
      { "id": "5d0345f7-da7c-44e8-bd6c-a8c08c806227" }
    ]
  }'

Device Signature (SDK Requests)

When the Mobile SDK calls this endpoint with the transaction token (Authorization: Bearer …), it also sends Device-Id, X-Device-Key-Id and X-Device-Signature on a tenant with the device signature check enabled. The credential named by X-Device-Key-Id must be ACTIVE and registered for the same Device-Id; otherwise the request is rejected with access_denied_exception. See Request Signing for when the headers are required.

Response

{
  "data": {
    "status": "success",
    "auth_check": {
      "score": 0.98,
      "result": "matched"
    },
    "request_id": "cfc7b8d5-f2e2-437b-80e5-d600dfad26e2",
    "authentication_key": "<AUTHENTICATION_KEY>"
  },
  "errors": [],
  "success": true,
  "code": 0,
  "message": "Success"
}

Field	Type	Description
data.status	string	success or failure.
data.auth_check	object	The authentication verdict. Present when success is true.
data.auth_check.result	string	matched, unmatched or unsure.
data.auth_check.score	float	How likely the presented face matches the profile, range 0–1.
data.request_id	string	Request ID; quote it to CAKE Support when checking logs.
data.authentication_key	string	The key your backend redeems at Verify Transaction Authentication Key.

WARNING

Do not approve the action on auth_check.result as reported by the app. Redeem the authentication_key from your backend and decide on that result — a client can claim any verdict it likes. Treat unsure as a distinct outcome for manual review, not a soft matched.

Errors

Code	Message
2001003	Image sent to the server has no faces.
2001006	Faces detected from images sent to the server are not matched.
2001008	Face has been registered on the system.
2001009	Image sent to the server has multiple faces.
2001010	Access ID not found.
2001011	Verify selfie / id_card liveness failed.
2001012	Verify selfie / id_card sanity failed.
2001016	Face auth rate limit exceeded.
2001017	Face auth brute force limit exceeded.
2001025	Selfie image sent to the server has length not equal to configuration.
2001026	Images sent to server are duplicated.
2002201	Face authentication did not match (verdict unsure).
2002205	Face authentication did not match (verdict unmatched).
2002206	User profile is locked.
2009005	SDK version is no longer supported. Please update the app.
401100	You are not authorized to perform the action.
4001000	Input parameter violates a constraint.
4001001	The X-TV-Timestamp header is expired, need a newer one.
4001002	Selfie or original image have more than 1 faces.
4041000	The image ID is not found in DB.
4041001	User not found.
4091000	The user_id has been registered.
4131000	The input image size exceeds the allowed limit (15MB).
4151000	The provided image format is not supported (JPG/PNG).
4291000	The number of requests exceeded your throughput limit.
5001000	Some unexpected error occurs while processing the request.

Code	Description
access_denied_exception	You are not authorized to perform the action.
invalid_parameter_exception	Input parameter violates a constraint.
request_time_too_skewed	The X-TV-Timestamp header is expired, need a newer one.
incorrect_number_of_faces	Selfie or original image have more than 1 faces.
image_not_found_exception	The image ID is not found in DB.
user_profile_not_found_exception	The profile of user not found.
user_profile_locked	User profile has been locked.
face_auth_rate_limit_exceeded	Face auth rate limit exceeded.
face_auth_brute_force_limit_exceeded	Face auth brute force limit exceeded.
sdk_version_unsupported	The SDK is older than the minimum version your tenant accepts for device-signed requests.
image_too_large_exception	The input image size exceeds the allowed limit (15MB).
invalid_image_format_exception	The provided image format is not supported (JPG/PNG).
rate_limit_exception	The number of requests exceeded your throughput limit.
duplicated_image	Images sent to server are duplicated.
selfie_image_invalid	Selfie image sent to the server has length not equal to configuration.
sanity_check_failed	Verify selfie / id_card sanity failed.
liveness_check_failed	Verify selfie / id_card liveness failed.
image_has_no_faces	Image sent to the server has no faces.
image_has_multiple_faces	Image sent to the server has multiple faces.
face_already_registered	Face has been registered on the system.
compare_faces_not_matched	Faces detected from images sent to the server are not matched.
internal_server_error	Some unexpected error occurs while processing the request.

A failed match is an error, not a success: true with a negative verdict: 2002205 for unmatched and 2002201 for unsure. Repeated failures raise face_auth_brute_force_limit_exceeded and then lock the profile with 2002206.

Next Steps

• Verify Transaction Authentication Key — redeem the key returned here
• Unlock Profile — clear a lock after repeated failures