Face Authentication token generation

Requirements

• API key pair
• A successful verification has to be already made - scanRef
• Face authentication token generation via API enabled (done by iDenfy's staff)
• Face authentication credits

Customize your Address Verification to enhance user experience

• Verify users quickly with face authentication.
• Authenticate faces using matching and passive liveness.
• Enhance KYC/AML compliance, prevent identity fraud.
• Compares live face to ID document photo.
• Access verification insights via dashboard access.

Read more

---

Introduction

This guide is for token generation and checking if the user can use face authentication. The token itself is needed to complete SDK initialization or iFrame integration, and checking if the user can use token generation is recommended, as it can help you verify if the user has completed verification and if the verification type is identification (verified with face and document).

1. Check face authentication status

face authentication status

Authorization: API key pair
Method: GET
Endpoint: https://ivs.idenfy.com/identification/facial-auth/{scanRef}/check-status/?method=FACE_MATCHING

Request

Once you call the endpont using scanRef the JSON response will respond with one of the following authentication types:

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

note

If verification with provided scanRef doesn't exist(deleted or not real scanRef provided), endpoint https://ivs.idenfy.com/identification/facial-auth/{scanRef}/check-status/?method=FACE_MATCHING returns status code 404.

Response example

{
  "type": "AUTHENTICATION"
}

---

2. Generate the authToken

generate authToken

Authorization: API key pair
Method: POST
Endpoint: https://ivs.idenfy.com/partner/authentication-info

note

if AUTHENTICATION_TYPE is IDENTIFICATION, please use the regular identification endpoint for generating a token. Look at verification token generation guide

Additionally, a locale value can be passed to force a specific locale and 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):

generateDigitString description

generateDigitString is optional; if provided, it returns a digitString to be used for face authentication on iDenfy's mobile app. Flow example:

• Your system calls our API endpoint to generate a face authentication session token, and we return a verification code.
• On your platform, you prompt the user to open the iDenfy app and enter the returned digitString code.
• The user takes a selfie, closes the app, and returns to your platform.
• Once your system receives the results via webhook, it either allows the user to proceed or, if the authentication fails, prompts them to retry by generating a new code.

Request example

{
  "scanRef": "scanRef",
  "type": "AUTHENTICATION_TYPE",
  "method": "FACE_MATCHING",
  "generateDigitString": true
}

Response example

{
  "scanRef": "scanRef",
  "type": "AUTHENTICATION_TYPE",
  "generateDigitString": true,
  "method": "FACE_MATCHING",
  "locale": "en",
  "lifetime": 3600
}