Face authentication token geration

(for SDK & iFrame)

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

You can check face authentication status by calling the HTTP GEThttps://ivs.idenfy.com/identification/facial-auth/{scanRef}/check-status/?method=FACE_MATCHING with basic auth headers where username is API key and password is API secret.

note

API key and API secret can be retrieved from the dashboard or contacting iDenfy's sales team:

• sales@idenfy.com
• via Dashboard

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

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.

2. Generate the authToken

The next step, after verifying that the user can use face authentication, is to receive the face authentication token itself. You can do this 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 from the dashboard or contacting iDenfy's sales team:

• sales@idenfy.com
• via Dashboard

The JSON body structure is the following:

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

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

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

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.

The JSON response will have the following structure:

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

All you need from the response is the token that will be used for SDK initialization and iFrame integration.