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.
API key and API secret can be retrieved from the dashboard or contacting iDenfy's sales team:
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 |
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.
API key and API secret can be retrieved from the dashboard or contacting iDenfy's sales team:
The JSON body structure is the following:
{
"scanRef": "scanRef",
"type": "AUTHENTICATION_TYPE",
"method": "FACE_MATCHING",
"generateDigitString": true
}
if AUTHENTICATION_TYPE is IDENTIFICATION, please use the regular identification endpoint for generating a token. Look at verification token generation guide
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": "scanRef",
"type": "AUTHENTICATION_TYPE",
"generateDigitString": true,
"method": "FACE_MATCHING",
"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.