Create Face Auth Session

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:

Name	Description
`AUTHENTICATION`	The user can authenticate by face
`ENROLLMENT`	The user must be enrolled before they can authenticate
`IDENTIFICATION`	The user must perform a full identification again

ENROLLMENT is only excluded when you pass method=FACE_MATCHING, as in the endpoint above. Omit the parameter or request active liveness and the response can also be ENROLLMENT.

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 Session Token

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. IDENTIFICATION cannot be passed as type on this endpoint — creation accepts only AUTHENTICATION or ENROLLMENT.

Request Parameters

Key	Required	Description
`scanRef`	Yes	The completed verification the user authenticates against
`method`	Yes	`FACE_MATCHING` or `ACTIVE_LIVENESS`
`type`	No	`AUTHENTICATION` (default) or `ENROLLMENT`
`lifetime`	No	Session duration in seconds. Default `3600` (1 hour), minimum `0`, maximum 30 days
`locale`	No	Forces a specific locale
`generateDigitString`	No	Returns a `digitString` for the mobile app flow

FACE_MATCHING supports authentication only.
ACTIVE_LIVENESS authentication fails unless the user was enrolled first with type: ENROLLMENT.

When generateDigitString is true, lifetime is additionally capped by a partner-level setting that defaults to 24 hours. The 30-day maximum does not apply to these sessions, and a longer lifetime returns an error.

Creation returns 400 — not 404 — if the scanRef is invalid or deleted. Insufficient face authentication credits also return 400.

generateDigitString description

generateDigitString is optional. If provided, it returns an 8-digit digitString to be used for face authentication on the iDenfy mobile app, or sent to the user as an SMS short link. The flow is as follows:

Your system calls the API endpoint to create a face authentication session, and a verification code is returned.
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 prompts them to retry by generating a new code.

The code has no separate lifetime — it expires with the session.

Request Example

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

Response Example

{
  "token": "3FA5TFPA2ZE3LMPGGS1EGOJNJE",
  "type": "AUTHENTICATION",
  "maxAttemptCount": 1,
  "digitString": "12345678",
  "locale": "en"
}

Field	Description
`token`	Session token. Use it for SDK initialization or to build the session URL
`type`	`AUTHENTICATION` or `ENROLLMENT`
`maxAttemptCount`	Always `1` — a session allows a single attempt
`digitString`	8-digit code, returned only when `generateDigitString` was `true`
`locale`	Session locale

The response contains no expiry value and no session URL. Build the URL yourself from the token — see Face Auth iFrame.

Start Here

ID Verification (KYC)

Business Verification (KYB)

AML Screening

Face Authentication

Age Estimation

Bank Card Verification

Fraud Prevention

Bank Verification

Going Live

Reference

Learn More

Introduction

1. Check Face Authentication Status

2. Create the Session Token

Request Parameters

Request Example

Response Example

Learn More

​Introduction

​1. Check Face Authentication Status

​2. Create the Session Token

​Request Parameters

​Request Example

​Response Example

Introduction

1. Check Face Authentication Status

2. Create the Session Token

Request Parameters

Request Example

Response Example