---
title: "Facial authentication (1:1 Authentication) - Rest PKI Core"
description: "1:1 facial authentication in Rest PKI Core: compares the face captured with a liveness check to a biometric already enrolled. See how to create the session."
canonical: "https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/bio-sessions/authentication"
locale: "en"
product: "Rest PKI Core"
last_updated: "2026-10-12"
---

# Facial authentication (1:1 Authentication) - Rest PKI Core

- Compares the face captured in real time with a previously enrolled biometric, confirming that the user really is who they claim to be.
- The photo is collected through a liveness check.

## Creating the session
To create an authentication session, use the `StartAuthenticationSessionAsync` method of the client libs, passing a
`StartBioAuthenticationSessionRequest`.

This method makes a `POST` request to `/api/bio/sessions/authentication` [(Swagger)](https://core.pki.rest/swagger/index.html#operations-BioSessions-post_api_bio_sessions_authentication).

### Parameters (`StartBioAuthenticationSessionRequest`)
| **Parameter**                          | **Required?**    | **Type** | **Description** |
| -------------------------------------- | ---------------- | -------- | --------------- |
| **ReturnUrl**                          | Conditional*     | String   | URL to redirect the user to after the biometric check. [(see details)](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/bio-sessions#redirect-flow-returnurl)
| **TrustedOrigin**                      | Conditional*     | String   | URL of your site where the widget is embedded. [(see details)](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/bio-sessions#embedded-flow-widgettrustedorigin)
| **PlatformPreference**                 | No               | Enum     | Sets the platform preference and the QR code behavior. [(see details)](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/bio-sessions#general-parameters)
| **FaceCaptureProvider**                | No               | Enum     | Sets the biometric provider. [(see details)](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/bio-sessions#face-capture-session-parameters)
| **Subject**                            | Yes              | Object   | Reference to the user

> **Tip**
>
> *You must pass at least one of the two parameters ([see the difference between ReturnUrl and TrustedOrigin](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/bio-sessions#frontend-flows)):
> - `ReturnUrl` (for the redirect flow)
> - `TrustedOrigin` (for the widget)

### Parameters (`Subject`)
| **Parameter**                  | **Required?**     | **Type** | **Description** |
| ------------------------------ | ----------------- | -------- | --------------- |
| **Id**                         | Conditional*      | Guid     | Id of the enrollment, generated by Rest PKI Core
| **Identifier**                 | Conditional*      | String   | External identifier of the user.

> **Tip**
>
> *You must pass at least one of the two parameters:
> - (recommended) `Subject.Identifier`: use the same `SubjectIdentifier` used in the enrollment session.
> - (advanced) `Subject.Id`: if you stored the `Subject` Id returned by the enrollment session, you can use it here. Beware: if the previous
>   enrollment is deleted, a new enrollment for the same `SubjectIdentifier` gets a different Id.

### Response example

The request to `StartAuthenticationSessionAsync` returns the following response:

```json
{
  "sessionType": "Authentication",
  "sessionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "sessionUrl": "string"
}
```

### Frontend integration
Once your backend has obtained the `sessionUrl` from the API, forward it to your frontend. From there, the flow follows the interface you chose:

- **Embedded flow (widget)**: your application passes the URL to the JavaScript component, which starts the capture inside your page.

- **Redirect flow**: your application sends the user to the URL received, where the capture takes place.

> **Tip**
>
> If you are unsure how to implement each model, see [Frontend flows](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/bio-sessions#frontend-flows).

---

## Completing the session

To complete an authentication session, use the `CompleteAuthenticationSessionAsync` method of the client libs, passing a
`CompleteBioSessionRequest`.

This method makes a `POST` request to `/api/bio/sessions/authentication/completion` [(Swagger)](https://core.pki.rest/swagger/index.html#operations-BioSessions-post_api_bio_sessions_authentication_completion).

This method is the final step. The ticket can be used only once.

> **Tip**
>
> Call the completion only at the end of the process, sending the ticket you received to validate the result and close the session.

### Response example

```json
{
  "subjectIdentifier": "string",
  "subjectId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "failure": "CaptureFailed",
  "sessionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "success": true,
  "resultDataAvailable": true
}
```
* **subjectIdentifier**: external identifier of the user. [(see details)](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/bio-sessions#user-identifier-subjectidentifier)
* **subjectId**: Id of the enrollment.
* **failure**: tells whether a failure occurred during the session; see the list of failures below.
* **sessionId**: Id of the Rest PKI Core session.
* **success**: whether the authentication session succeeded.
* **resultDataAvailable**: if `true`, you can fetch the photos collected in the session.

##### Main failures

| **Enum**                          | **Description**                                    |
| --------------------------------- | -------------------------------------------------- |
| CaptureFailed                     | The image capture could not be finished. It usually happens when the user interrupts it. |
| LivenessFailed                    | The user did not pass the liveness check: the number of attempts exceeded the limit. |
| NoMatch                           | Not enough match between the biometric collected and the one previously enrolled. |
| BadImage                          | The captured image does not have enough quality to be processed. It may be caused by poor lighting, blur, excessive glare or a partially covered face. |

## Checking the status

You can check the current state of a session at any time using its `sessionId`. This is useful to monitor whether the user has started the
session, or whether it has expired, even before it is completed.

> **Tip**
>
> Use `GetAuthenticationSessionStatusAsync` to follow the progress of an active session by its `sessionId`.

The response of this endpoint is exactly the same as the [response example of `CompleteAuthenticationSessionAsync`](https://docs.lacunasoftware.com/en-us/articles/rest-pki/core/integration/bio-sessions/authentication#response-example-1).

**Demos and samples**

- Live demo: [Enroll and authenticate your face](https://try.lacunasoftware.com/en/lacuna-bio/enroll-and-authenticate-your-face)