> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.idenfy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Face Auth Session

> Create a face authentication session token via the iDenfy API using a previous verification scanRef for biometric re-authentication.

<Note>
  **Requirements**

  * **API** key pair
  * A **successful** verification already completed (`scanRef`)
  * Face authentication session creation via API **enabled** (done by iDenfy staff)
  * Face authentication **credits**
</Note>

<Card title="Learn More" icon="globe" href="https://idenfy.com/face-authentication-service/">
  Verify users quickly with face authentication -- compares a live face to the ID document photo using matching and passive liveness detection.
</Card>

***

## 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

<Info>
  **Authorization:** `API key pair`
  **Method:** `GET`
  **Endpoint:** `https://ivs.idenfy.com/identification/facial-auth/{scanRef}/check-status/?method=FACE_MATCHING`
</Info>

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       |
| `IDENTIFICATION` | The user must perform an identification |

<Note>
  If verification with the provided `scanRef` does not exist (deleted or invalid), the endpoint returns status code **404**.
</Note>

**Response example:**

```json theme={"system"}
{
  "type": "AUTHENTICATION"
}
```

***

## 2. Create the `authToken`

<Info>
  **Authorization:** `API key pair`
  **Method:** `POST`
  **Endpoint:** `https://ivs.idenfy.com/partner/authentication-info`
</Info>

<Note>
  If the authentication type is `IDENTIFICATION`, use the regular identification endpoint for creating a session. See the [session creation guide](/kyc/generate-token).
</Note>

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**.

<Accordion title="generateDigitString description">
  `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.
</Accordion>

### Request Example

```json theme={"system"}
{
  "scanRef": "scanRef",
  "type": "AUTHENTICATION_TYPE",
  "method": "FACE_MATCHING",
  "generateDigitString": true
}
```

### Response Example

```json theme={"system"}
{
  "scanRef": "scanRef",
  "type": "AUTHENTICATION_TYPE",
  "generateDigitString": true,
  "method": "FACE_MATCHING",
  "locale": "en",
  "lifetime": 3600
}
```