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

# FaceAuth Getting Started

> FaceAuth further verifies identity by comparing the selfie of a user approved in the ID Check process with the selfie captured during FaceAuth. This page covers the two delivery methods (URL / API), the Face Auth URL QueryString structure, and the request parameter definitions.

<Info>
  **Related reading**

  * Creating a FaceAuth project in the dashboard and configuring policy (thresholds, liveness, occlusion) and token expiration → [FACE AUTH Guide](/dashboard/en/face-auth-guide)
  * Add-on fundamentals shared by every add-on (API key issuance, request quotas, HTTP response status codes) → [Add-on Getting Started](/en/idcheck/add-on/overview)
</Info>

## How FaceAuth Is Delivered — Two Options

FaceAuth can be delivered in two ways. **We recommend the Face Auth URL method**, which removes the need to build your own camera UI and supports Active Liveness.

<CardGroup cols={2}>
  <Card title="A. Face Auth URL (Recommended)" icon="link" href="/dashboard/en/face-auth-guide">
    Selfie capture happens on an ARGOS-hosted page (similar to Liveform). No client-side camera implementation is required, and the project policy can enable **Liveness (Passive/Active)** and occlusion (mask/helmet) controls.
  </Card>

  <Card title="B. POST /faceauth API" icon="code" href="/en/idcheck/add-on/post-faceauth">
    Your app implements the camera UI and posts the captured `faceImage` file to the API. **Active Liveness is not supported** — only face similarity is compared.
  </Card>
</CardGroup>

<Tip>
  **If spoofing via replayed screens or printed photos is a concern, use the URL method.** The POST API method judges a single submitted image on similarity alone and cannot verify that the user is physically present. The URL method lets you set a **Liveness threshold** in the project policy to block screen-replay and still-photo attacks.
</Tip>

For dashboard policy setup (thresholds, liveness, occlusion) and end-to-end use cases for both methods, see the [FACE AUTH guide](/dashboard/en/face-auth-guide). The remainder of this page covers parameters and the auth flow for **Method A (Face Auth URL)**. For **Method B (POST API)**, see the [POST/Faceauth](/en/idcheck/add-on/post-faceauth) page.

## QueryString for Accessing FaceAuth

FaceAuth is a sub-project of ID check, and administrators can create as many projects as they want. To deliver additional authentication via the FaceAuth URL method, **use the Face Auth URL within the Add-on project.** <br />
To reference a submission\_Id that has been approved through ID document or Knowledge-based where a selfie image exists, it must be added to the URL through the `encrypted` query parameter, and for security purposes, it must always be used in an encrypted state.<br />
Encryption must use the API key within the FaceAuth project and uses AES-256. <br />
For detailed methods, please refer to [Query String Encryption](/en/idcheck/getting-started/encrypt-and-decrypt-data/overview#2-query-string-encryption).

<Warning>
  **The plaintext you encrypt is JSON — not a query string.**

  Encrypting a string built by joining `key=value` pairs with `&` (for example `sid=...&authUserId=...`) leaves `sid` unreadable and verification never starts. **Serialize a JSON object (`JSON.stringify`) and encrypt that string**, then pass the result as `encrypted`.

  In this case the screen shows **"Page not found"** rather than an error-code page, which makes the cause hard to identify. For the diagnostic order, see [Face Auth URL Validation and Error Handling](/en/idcheck/add-on/faceauth-url-errors#2-1-missing-required-parameters).
</Warning>

<Warning>
  **Face Auth does not run without a query string.**

  A URL carrying only `pid` will not start verification — the `sid` to reference must be encrypted and passed inside `encrypted`. If it is missing, the user is redirected to the [`PV-40015` error page](/en/idcheck/add-on/faceauth-url-errors#2-entry-stage-validation-failures).
</Warning>

### Step 1 — Prepare the plaintext (JSON) to encrypt

<CodeGroup>
  ```json Basic: only the submission_Id to reference (minimum runnable form) theme={null}
  {
    "sid": "{submission_Id}"
  }
  ```

  ```json All parameters: sid, authUserId, authCf1, authCf2, authCf3, token theme={null}
  {
    "sid": "{submission_Id}",
    "authUserId": "{user Id}",
    "authCf1": "{additional_info}",
    "authCf2": "{additional_info}",
    "authCf3": "{additional_info}",
    "token": "{any tokenId}"
  }
  ```
</CodeGroup>

### Step 2 — Encrypt with the FaceAuth project API key (AES-256) and build the URL

```text Face Auth URL structure (this form alone does not run) theme={null}
  https://form.argosidentity.com/face-auth?pid={faceAuth_projectId}
```

```text The encrypted value passed in encrypted (runnable form) theme={null}
  https://form.argosidentity.com/face-auth?pid={faceAuth_projectId}&encrypted={encrypted}
```

<Warning>
  **The `encrypted` value must be URL-encoded.**

  AES-256 output (Base64) contains `+`, `/`, and `=`. Appending it to the URL without encoding makes `+` decode as a space, so **decryption itself fails** and `sid` cannot be read. Apply `encodeURIComponent` (or your language's URL-encoding function).
</Warning>

```javascript Full Node.js example theme={null}
const crypto = require('crypto');

function encrypt(data, apiKey) {
  const hashedKey = crypto.createHash('sha256').update(apiKey).digest();
  const cipher = crypto.createCipheriv('aes-256-ecb', hashedKey, null);
  return cipher.update(data, 'utf8', 'base64') + cipher.final('base64');
}

// Step 1: the plaintext is a serialized JSON object
const queryData = JSON.stringify({
  sid: 'submission_12345',
  authUserId: 'user123',
});

// Step 2: encrypt with the FaceAuth project API key, then URL-encode
const encrypted = encrypt(queryData, FACEAUTH_API_KEY);
const faceAuthUrl =
  `https://form.argosidentity.com/face-auth?pid=${FACEAUTH_PROJECT_ID}` +
  `&encrypted=${encodeURIComponent(encrypted)}`;
```

<Note>
  `pid` and `lang` are not subject to encryption — append them as plaintext outside `encrypted`.
</Note>

## Definition of Request Parameters

<ResponseField name="pid" type="string" required>
  Unique number assigned to the project when creating a FaceAuth project (automatically attached to the URL)
</ResponseField>

<ResponseField name="sid" type="string" required>
  submission\_Id approved through ID document or Knowledge-based (sid is used for distinction)
</ResponseField>

<ResponseField name="authUserId" type="string">
  User Id that the administrator will assign to the user (this could be the user Id in the administrator's service or the same userId used in ID document or Knowledge-based)
</ResponseField>

<ResponseField name="authCf1" type="string">
  Additional information that the administrator will assign to the user (e.g., email address, etc.)
</ResponseField>

<ResponseField name="authCf2" type="string">
  Additional information that the administrator will assign to the user (same as authCf1)
</ResponseField>

<ResponseField name="authCf3" type="string">
  Additional information that the administrator will assign to the user (same as authCf1)
</ResponseField>

<ResponseField name="token" type="string">
  Token that the administrator will add to the URL for security purposes. <br />
  **Note!**: This token operates separately from the pre-registered token in private mode.

  <Accordion title="How FaceAuth token works">
    The token is designed to assign a unique URL to each user when they authenticate through FaceAuth. <br />
    To apply a token, you must enable the token expiration condition setting option in the FaceAuth project, and it works as follows:

    * Count-based expiration: When the token is used once, the Token ID is immediately expired.
    * Time-based expiration: When the time has elapsed from the point when the token was used once, the Token ID is expired.

    This token operates separately from the main project's private mode token or pre-registered token. <br />
    For example, you can specify an arbitrary tokenId set by the administrator in the token, and even if you reuse the token used in the main project, it works because it is viewed separately.
    For a guide on enabling the token expiration condition setting option in the FaceAuth project, please refer to [FACE AUTH guide — Token Expiration Condition Settings](/dashboard/en/face-auth-guide#token-expiration-condition-settings).
  </Accordion>
</ResponseField>

<ResponseField name="lang" type="string">
  Display language of the Face Auth screen. Use a lowercase ISO 639-1 code (for example, `en`, `ko`). **Not subject to encryption — append it as plaintext outside `encrypted`** (for example, `?pid={faceAuth_projectId}&encrypted={encrypted}&lang=en`). When omitted, mobile follows the device language and PC follows the browser language. For the list of supported languages, see [Supported Languages](/en/idcheck/getting-started/liveform-languages).
</ResponseField>

<Note>
  For approved cases where no selfie image exists, the portrait image from the ID document will be used instead.
</Note>

<Card title="Face Auth URL Validation and Error Handling" icon="triangle-exclamation" href="/en/idcheck/add-on/faceauth-url-errors">
  A stage-by-stage reference for the error codes raised by QueryString validation failures, pre-load failures, and authentication failures — and the messages users actually see.
</Card>

## FaceAuth API Endpoints

<CardGroup cols={2}>
  <Card title=" POST/FaceAuth" icon="person-circle-plus" href="/en/idcheck/add-on/post-faceauth">
    FaceAuth Submission
  </Card>

  <Card title="GET/FaceAuth" icon="person-circle-check" href="/en/idcheck/add-on/get-faceauth">
    FaceAuth Retrieval
  </Card>

  <Card title="GET/FaceAuth/Image" icon="person-circle-check" href="/en/idcheck/add-on/get-faceauth_image">
    FaceAuth Image Retrieval
  </Card>

  <Card title="DELETE/FaceAuth" icon="person-circle-xmark" href="/en/idcheck/add-on/delete-faceauth">
    FaceAuth Deletion
  </Card>
</CardGroup>

## Webhooks

<CardGroup cols={2}>
  <Card title="Faceauth" icon="person-circle-plus" href="/en/idcheck/add-on/add-on-webhook">
    FaceAuth webhook
  </Card>

  <Card title="Token ID expiration" icon="clock" href="/en/idcheck/add-on/add-on-webhook-token">
    Token ID expiration webhook
  </Card>
</CardGroup>