Skip to main content
Requirements
  • API key pair
  • A successful verification already completed (scanRef)
  • Face authentication session creation 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 session creation and checking whether your user can use face authentication. You need the session token for SDK initialization or iFrame integration. Check the authentication status first to verify whether your 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. Create 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 creating a session. See the session creation guide.
You can also pass a locale value to force a specific locale, and a lifetime JSON body value 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 create a face authentication session, 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
}