Pular para o conteúdo principal

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

Parameters (StartBioAuthenticationSessionRequest)​

ParameterRequired?TypeDescription
ReturnUrlConditional*StringURL to redirect the user to after the biometric check. (see details)
TrustedOriginConditional*StringURL of your site where the widget is embedded. (see details)
PlatformPreferenceNoEnumSets the platform preference and the QR code behavior. (see details)
FaceCaptureProviderNoEnumSets the biometric provider. (see details)
SubjectYesObjectReference to the user
tip

*You must pass at least one of the two parameters (see the difference between ReturnUrl and TrustedOrigin):

  • ReturnUrl (for the redirect flow)
  • TrustedOrigin (for the widget)

Parameters (Subject)​

ParameterRequired?TypeDescription
IdConditional*GuidId of the enrollment, generated by Rest PKI Core
IdentifierConditional*StringExternal 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:

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

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

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​

{
  "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)
  • 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​
EnumDescription
CaptureFailedThe image capture could not be finished. It usually happens when the user interrupts it.
LivenessFailedThe user did not pass the liveness check: the number of attempts exceeded the limit.
NoMatchNot enough match between the biometric collected and the one previously enrolled.
BadImageThe 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.

View as Markdown