Face authentication for iFrame

Preconditions

There must be an approved KYC verification in order to generate new face authentication token with AUTHENTICATION status.

Check verification status

Before initializing face authentication, you need to check whether the user can use face authentication with the following path parameter as well as basic auth headers where username is API key and password is API secret, according to example below.

Example GET request using:

https://ivs.idenfy.com/identification/facial-auth/{scanRef}/check-status/?method=FACE_MATCHING

The JSON response will have the following structure:

{
"type": "AUTHENTICATION_TYPE"
}

Authentication type is an enum class with the following values:

Name	Description
`AUTHENTICATION`	The user can authenticate by face
`IDENTIFICATION`	The user must perform an identification

Create face authentication session token

For face authentication iFrame initialization, you need to generate an authToken.

You can receive it by calling the HTTP POST https://ivs.idenfy.com/partner/authentication-info request with the following JSON body structure as well as basic auth headers where username is API key and password is API secret.

note

API key and API secret can be retrieved by contacting iDenfy's tech support or iDenfy's sales team:

sales@idenfy.com
via Dashboard

The JSON body structure is the following:

{
  "scanRef": "8df398bb-7340-11ee-9aec-0221b1f59063",
  "type": "AUTHENTICATION",
  "method": "FACE_MATCHING"
}

Additionally, a lifetime JSON body value can be passed, which will set the duration of the session (By default it is 30 minutes, maximum duration is 30 days. Value is set with seconds):

{
  "scanRef": "8df398bb-7340-11ee-9aec-0221b1f59063",
  "type": "AUTHENTICATION",
  "method": "FACE_MATCHING",
  "lifetime": 3600
}

The JSON response will have the following structure:

{
"token": "AUTH_TOKEN",
"maxAttemptCount": 3
}

All you need from the response is the token.

Integration to iFrame

In order to have face authentication with iFrame, you will have to directly insert verification platform URL (https://face.authentication.idenfy.com/?token=) with token query string parameter into your iframe tag. The token can be retrieved after generating a token.

After the process is finished, you may close the iframe and display a desired page to your client.

Examples

Query string parameter name	Example value
`token`	`3FA5TFPA2ZE3LMPGGS1EGOJNJE`

An example redirect url:
https://face.authentication.idenfy.com/?token=3FA5TFPA2ZE3LMPGGS1EGOJNJE

Example code

<!DOCTYPE html>
<html>
  <body>
    <iframe
      id="iframe"
      style="width: 80%; height: 800px"
      src="https://face.authentication.idenfy.com/?token=3FA5TFPA2ZE3LMPGGS1EGOJNJE"
      allow="camera"
    ></iframe>
​
    <p id="display"></p>
​
    <script>
      window.addEventListener('message', receiveMessage, false);
      function receiveMessage(event) {
        console.log(event);
        // ...
      }
    </script>
  </body>
</html>

Posssible values to check status of face authentication:

Information about the face authentication statuses could be found in console, on data object.

Information about the verification auto status status:

Name	Description
`APPROVED`	The user completed a face authentication process, and it was approved.
`FAILED`	The user completed a face authentication process, but it failed.

info

To assess the face authentication session, the webhook(s) sent from our back-office should be evaluated, as the statuses in the iFrame console are complementary.

Webhook

It is possible to receive information when actions related to face authentication are being performed by setting up a FACIAL_AUTHENTICATION notification type webhook.

Example of an EXPIRED token response:

{
  "id": "8d471b4c-3822-4547-aec5-a9d0cc0aa105",
  "scanRef": "8df398bb-7340-11ee-9aec-0221b1f59063",
  "clientId": "FD155HLZ5Z",
  "status": "EXPIRED",
  "token": "UbYZnDdrTElsSDBQFeNkd8MxI9CpSEO0qR5jtRcz",
  "type": "AUTHENTICATION",
  "method": "FACE_MATCHING",
  "facePhoto": null,
  "failReason": null
}

Descriptions of possible `status` values

Name	Description
`SUCCESS`	Authentication is successfull. This message is also sent upon successful ENROLLMENT.
`FAILED`	Authentication failed due to fraudulent activity or other possible vulnerabilities. This message is also sent upon ENROLLMENT failure.
`EXPIRED`	Face authentication token expired before the user started the process.
`CANCELED`	Face authentication session was cancelled by the user.

Possible `failReason` values

FACE_MISMATCH
FAKE_FACE
VIRTUAL_CAMERA
FACE_NOT_FOUND
TOO_MANY_FACES
FACE_ANGLE_TOO_LARGE
FACE_TOO_SMALL
FACE_CLOSE_TO_BORDER
FACE_TOO_CLOSE
FACE_CROPPED
FACE_IS_OCCLUDED
EYES_CLOSED
FAILED_TO_PREDICT_LANDMARKS
PROBABILITY_TOO_SMALL
FAKE_CAPTURE
DUPLICATE_IMAGE

note

New failReason values could be introduced in the future and added at any time.

Face authentication for iFrame

Preconditions​

Check verification status​

Example GET request using:​

Create face authentication session token​

Integration to iFrame​

Examples​

Example code​

Posssible values to check status of face authentication:​

Webhook​

Example of an EXPIRED token response:​

Descriptions of possible status values​

Possible failReason values​