Skip to main content
Requirements
  • API key pair
  • A successful verification already completed (scanRef)
  • Face authentication token generation via API enabled (done by iDenfy staff)
  • Face authentication credits

Learn More

Verify users quickly with face authentication — compares a live face to the ID document photo using matching and passive liveness detection.

​
Introduction

This guide covers token generation and checking whether a user can use face authentication. The token is needed for SDK initialization or iFrame integration. Checking the authentication status first is recommended, as it verifies whether the user has completed identification (verified with face and document).

​
1. Check Face Authentication Status

Authorization: API key pair Method: GET Endpoint: https://ivs.idenfy.com/identification/facial-auth/{scanRef}/check-status/?method=FACE_MATCHING
Once you call the endpoint using the scanRef, the response will contain one of the following authentication types:
NameDescription
AUTHENTICATIONThe user can authenticate by face
IDENTIFICATIONThe user must perform an identification
If verification with the provided scanRef does not exist (deleted or invalid), the endpoint returns status code 404.
Response example: 
{
  "type": "AUTHENTICATION"
}

​
2. Generate the authToken

Authorization: API key pair Method: POST Endpoint: https://ivs.idenfy.com/partner/authentication-info
If the authentication type is IDENTIFICATION, use the regular identification endpoint for generating a token. See the 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 to set the session duration. The default is 30 minutes, with a maximum of 30 days. The value is set in seconds.
generateDigitString is optional. If provided, it returns a digitString to be used for face authentication on the iDenfy mobile app. The flow is as follows:
  1. Your system calls the API endpoint to generate a face authentication session token, and a verification code is returned.
  2. On your platform, you prompt the user to open the iDenfy app and enter the returned digitString code.
  3. The user takes a selfie, closes the app, and returns to your platform.
  4. Once your system receives the results via webhook, it either allows the user to proceed or 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
}