Authenticate User V3

/authenticateUser/v3

Description

This service provides persistence of Biometric Templates and facial Authentication 1:1 against stored templates. It supports two operational modes within a single Endpoint, determined by the request body:

• Enroll Mode: Validates the liveness check and performs facial Matching between a provided Biometric Template and a live capture, then persists the template associated with a userId.

• Authenticate Mode: Retrieves a previously stored template by userId and performs facial Matching 1:1 and liveness check validation against a new live capture.

Functionality

• Enroll: The userId together with the Biometric Template (templateRaw) and the best tokenized image (bestImageToken). The liveness check and facial Matching are validated. If both are successful, the template associated with the user is persisted. If the user already exists, the template is updated.

• Authenticate: The userId together with the bestImageToken of the current session. The stored template is retrieved and a 1:1 Matching is performed against the live capture. The authentication result is returned with the similarity score.

Use cases

1. Client without prior Onboarding with Facephi: During password recovery, the client performs an Onboarding that generates a Biometric Template. This template is enrolled through this Endpoint and is associated with a userId. Future password recoveries authenticate directly against the stored template without repeating the Onboarding.

2. Client with prior Onboarding with Facephi: The client already has a stored template. Subsequent authentications use the 1:1 Matching Flow against the stored template.

Integration

Requires the implementation of the Selphi Mobile Widget or the Selphi Web Widget to generate the bestImageToken and the Biometric Template (templateRaw).

Endpoint

POST /services/authenticateUser/v3

Headers

Header	Type	Required	Description
x-api-key	String	Yes	Tenant API Key
Content-Type	String	Yes	application/json
family	String	No	Required family Header for Tracking

All calls to the Endpoints with Tracking in Identity Platform must contain the header family.

---

Enroll Mode

Enrolls or updates a Biometric Template for a user. It requires the liveness check validation and facial Matching to be successful before persisting the template.

The presence of the field templateRaw in the request body activates this mode.

Request body

Content-Type: application/json

Parameters

Parameter	Type (Content)	Required	Description
userId	String	Yes	Unique user identifier. Must have at least 2 characters.
templateRaw	String (Base64)	Yes	Facial Biometric Template generated from the best image during the Onboarding process. Its presence activates the Enroll mode.
bestImageToken	String (Base64)	Yes	Best tokenized facial image generated by the Selphi Widget. It is used for liveness check validation and facial Matching against the templateRaw to verify that they correspond to the same live person.
tracking	JSON Object	No	Object containing Tracking information.
extraData	String (Base64)	No	Token generated by the SDK Mobile/Web that contains tokenized Tracking information.
operationId	String	No	Operation identifier generated by the SDK Mobile/Web.

Request example: Enroll

{
    "userId": "user-001",
    "templateRaw": "BAEBAQIxLiHIhMPQWaUo…",
    "bestImageToken": "BgEBAQJksxGtVd++lRjN…",
    "tracking": {
        "extraData": "BQABAQG2gBNjuHN...",
        "operationId": "123e4567-e89b-12d3-a456-426614174000"
    }
}

Enroll behavior

1. liveness check: Validates that the bestImageToken corresponds to a live person.

2. Facial Matching: Performs a 1:1 Matching between templateRaw and bestImageToken to verify that they belong to the same person.

3. Persistence: If both checks pass, queries the userId:

   • If the user does not exist: creates the user and stores the template.

   • If the user already exists: updates the stored template with the new one.

4. TTL (if configured): The template Token has a configurable validity period for use in the service. Once expired, it is no longer valid for Enroll.

---

Authenticate Mode

Authenticates a user by comparing a live capture against their previously stored Biometric Template. This mode is activated when templateRaw do not is included in the request body.

Important: The user must have been previously enrolled (through Enroll mode or the v1/v2 self-registration Flow) before they can be authenticated. Attempting to authenticate an unenrolled user returns an error User not found.

Parameters

Parameter	Type (Content)	Required	Description
userId	String	Yes	Unique identifier of the user to authenticate. Must have at least 2 characters.
bestImageToken	String (Base64)	Yes	Best tokenized facial image from the current authentication session. It is used for liveness check validation and 1:1 Matching against the stored template.
tracking	JSON Object	No	Object containing Tracking information.
extraData	String (Base64)	No	Token generated by the SDK Mobile/Web that contains tokenized Tracking information.
operationId	String	No	Operation identifier generated by the SDK Mobile/Web.

Request example: Authenticate

{
    "userId": "user-001",
    "bestImageToken": "BgEBAQJksxGtVd++lRjN…",
    "tracking": {
        "extraData": "BQABAQG2gBNjuHN...",
        "operationId": "123e4567-e89b-12d3-a456-426614174000"
    }
}

Authentication behavior

1. User lookup: Retrieves the stored template associated with the userId.

2. TTL check: If the template has a configured expiration and it has been exceeded, returns Template expired.

3. liveness check: Validates that the bestImageToken corresponds to a live person.

4. Facial Matching: Performs a 1:1 Matching between the stored template and the bestImageToken.

5. Result: Returns the Matching result including similarity score, authentication status, and liveness check diagnosis.

---

Responses

200 Success

Response parameters

Identifier	Type	Description
serviceResultCode	Integer	Code indicating the overall result of the service execution. See the Service Result Code table below.
serviceResultLog	String	Descriptive field for the execution result. Empty in case of success.
serviceFacialSimilarityResult	Float	Value indicating the facial similarity between the template and the bestImageToken. 1.0 = 100%. Present only when Biometric Matching is performed.
serviceFacialAuthenticationLog	String	Descriptive field for the facial Authentication result (e.g. "Positive", "Negative", "Uncertain"). Present only when Biometric Matching is performed.
serviceFacialAuthenticationResult	Integer	Code indicating the result of facial Authentication. See Table 2 - Service Facial Authentication Result.
serviceLivenessLog	String	Descriptive field for the passive liveness check result (e.g. "Live", "Spoof"). Present only when the liveness check is evaluated.
serviceLivenessResult	Integer	Code indicating the result of the passive liveness check evaluation. See Table 3 - Service Liveness Result.
timestamp	String	Timestamp (UTC) of the response in format: YYYY-MM-DDThh🇲🇲ssZ
transactionId	String	Transaction identifier associated with the request processed by the API.

Service Result Code

The serviceResultCode indicates the overall result of the service execution:

serviceResultCode	Description	HTTP code
0	Successful operation (Enroll completed or user authenticated).	200
-101	The bestImageToken does not correspond to a live person.	200
-102	User Authentication failed — negative facial match.	200
-103	User not found (authenticate mode only).	404
-104	Template not found — the user exists but has no stored template.	404
-105	Template expired — TTL exceeded, the template is no longer available.	200

Service Liveness Result

The serviceLivenessResult indicates the result of the passive liveness check evaluation:

Service Liveness Result

Code	Result	Description
0	None	The liveness check could not be evaluated.
1	Spoof	DEPRECATED. Use 'NoLive' instead.
2	Uncertain	DEPRECATED
3	Live	The subject is assumed to be alive.
4	NoneBecauseBadQuality	The liveness check could not be evaluated due to poor image quality.
5	NoneBecauseFaceTooClose	The liveness check could not be evaluated because the detected faces are too close to the edges.
6	NoneBecauseFaceNotFound	The liveness check could not be evaluated because no faces were detected.
7	NoneBecauseFaceTooSmall	The liveness check could not be evaluated because the detected faces are too small.
8	NoneBecauseAngleTooLarge	The liveness check could not be evaluated because the angle between faces exceeds the allowed limit.
9	NoneBecauseImageDataError	The liveness check could not be evaluated due to image format errors.
10	NoneBecauseInternalError	The liveness check could not be evaluated due to an internal error.
11	NoneBecauseImagePreprocessError	The liveness check could not be evaluated due to an image preprocessing error.
12	NoneBecauseTooManyFaces	The liveness check could not be evaluated because too many faces were detected in the image.
13	NoneBecauseFaceTooCloseToBorder	The liveness check could not be evaluated because the face is too close to the edge.
14	NoneBecauseFaceCropped	The liveness check could not be evaluated because the face is cropped.
15	NoneBecauseLicenseError	The liveness check could not be evaluated due to a license error.
16	NoneBecauseFaceOccluded	The liveness check could not be evaluated because the face is occluded.
17	NoLive	No life was detected.
18	NoneBecauseEyesClosed	The liveness check could not be evaluated because the person's eyes are closed.

Service Facial Authentication Result

The serviceFacialAuthenticationResult indicates the result of the facial matching operations:

Service Facial Authentication Result

Code	Result	Description
0	NONE	Facial verification could not be performed.
1	NEGATIVE	The process was executed successfully. The comparison of the facial pattern of the faces does not match.
3	POSITIVE	The process was executed successfully. The comparison of the facial pattern of the faces is positive. The value of serviceFacialSimilarityResult indicates the % similarity between the compared images.
4	NONE BECAUSE POSE EXCEED	Facial verification could not be performed due to the face position.
5	NONE BECAUSE INVALID EXTRACTIONS	Facial verification could not be performed due to problems in extracting the facial pattern.

Response example: Successful Enroll

{
    "serviceResultCode": 0,
    "serviceResultLog": "",
    "serviceFacialSimilarityResult": 0.9812,
    "serviceFacialAuthenticationLog": "Positive",
    "serviceFacialAuthenticationResult": 3,
    "serviceLivenessLog": "Live",
    "serviceLivenessResult": 3,
    "timestamp": "2026-04-20T15:12:07Z",
    "transactionId": "cd13a168-6eb0-4afd-bc88-408ca6a73437"
}

Response example: Successful Authentication (positive match)

{
    "serviceResultCode": 0,
    "serviceResultLog": "",
    "serviceFacialSimilarityResult": 0.9812,
    "serviceFacialAuthenticationLog": "Positive",
    "serviceFacialAuthenticationResult": 3,
    "serviceLivenessLog": "Live",
    "serviceLivenessResult": 3,
    "timestamp": "2026-04-20T15:12:28Z",
    "transactionId": "1ada7f96-44f2-48f1-87a5-0359621ae7a1"
}

Response example: Negative match

{
    "serviceResultCode": -102,
    "serviceResultLog": "User authentication failed",
    "serviceFacialSimilarityResult": 0.0192,
    "serviceFacialAuthenticationLog": "Negative",
    "serviceFacialAuthenticationResult": 1,
    "serviceLivenessLog": "Live",
    "serviceLivenessResult": 3,
    "timestamp": "2026-04-20T15:34:47Z",
    "transactionId": "d6e29c6c-0da2-4620-9ca7-f483c6950d72"
}

Response example: User not found

{
    "serviceResultCode": -103,
    "serviceResultLog": "User not found",
    "timestamp": "2026-04-20T15:12:29Z",
    "transactionId": "ca61856d-0eb8-49ca-8178-66346e0c75ab"
}

400 Bad Request

{
    "status": 400,
    "title": "Bad Request",
    "detail": "Invalid request.",
    "type": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400",
    "errors": [
        "userId is required"
    ]
}

401 Unauthorized

{
    "message": "Unauthorized"
}

403 Forbidden

{
    "Message": "User is not authorized to access this resource with an explicit deny"
}

404 Not Found

{
    "serviceResultCode": -103,
    "serviceResultLog": "User not found",
    "timestamp": "2026-04-20T15:12:29Z",
    "transactionId": "ca61856d-0eb8-49ca-8178-66346e0c75ab"
}

502 Bad Gateway

{
    "status": 502,
    "title": "Bad Gateway",
    "detail": "Server got an invalid response.",
    "type": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/502"
}

504 Gateway Timeout

{
    "message": "Endpoint request timed out"
}

---

Differences with v1/v2

Aspect	v1/v2	v3
Template field in request	registeredTemplateRaw	templateRaw
merchantReferenceId	Required	Not used
image / template as input	Supported	Not supported — only templateRaw + bestImageToken
Self-registration on first Authentication	Yes	No — explicit Enroll required
Template in the response	Yes (registeredTemplateRaw)	No (not returned for security — avoids unnecessary transfer of PII)
Liveness check + match on Enroll	N/A	Required before persisting
TTL / template expiration	Not supported	Supported (configurable by tenant via templateTTLSeconds)
New error codes	N/A	-104 (Template not found), -105 (Template expired)

---