FaceAuth Getting Started - ARGOS Identity

The FaceAuth API has moved to /v3/face-auth.The path, response structure, field names, and error format all differ from the previous endpoint /v3/faceauth. To move an existing integration, see FaceAuth Common Reference — Migrating from the previous API. The FaceAuth URL method (https://form.argosidentity.com/face-auth) is not affected by this change.

The Liveform URLs on this page are for US region projects. KR region projects use the host form-kr.argosidentity.com. See Regions for details.

Related reading

Creating a FaceAuth project in the dashboard and configuring policy (thresholds, liveness, occlusion) and token expiration → FaceAuth Guide
Add-on fundamentals shared by every add-on (API key issuance, request quotas, HTTP response status codes) → Add-on Getting Started

How FaceAuth Is Delivered — Two Options

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

A. FaceAuth URL (Recommended)

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.

B. POST /v3/face-auth API

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.

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.

For dashboard policy setup (thresholds, liveness, occlusion) and end-to-end use cases for both methods, see the FaceAuth guide. The remainder of this page covers parameters and the auth flow for Method A (FaceAuth URL). For Method B (POST API), see the POST/Face-auth page.

Query String 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 FaceAuth URL within the Add-on project.
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.
Encryption must use the API key within the FaceAuth project and uses AES-256.
For detailed methods, please refer to Query String Encryption.

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 FaceAuth URL Validation and Error Handling.

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

Step 1 — Prepare the plaintext (JSON) to encrypt

{
  "sid": "{submission_Id}"
}

{
  "sid": "{submission_Id}",
  "authUserId": "{user Id}",
  "authCf1": "{additional_info}",
  "authCf2": "{additional_info}",
  "authCf3": "{additional_info}",
  "token": "{any tokenId}"
}

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

FaceAuth URL structure (this form alone does not run)

  US region: https://form.argosidentity.com/face-auth?pid={faceAuth_projectId}
  KR region: https://form-kr.argosidentity.com/face-auth?pid={faceAuth_projectId}

The encrypted value passed in encrypted (runnable form)

  US region: https://form.argosidentity.com/face-auth?pid={faceAuth_projectId}&encrypted={encrypted}
  KR region: https://form-kr.argosidentity.com/face-auth?pid={faceAuth_projectId}&encrypted={encrypted}

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

Full Node.js example

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);
// KR region: https://form-kr.argosidentity.com
const faceAuthUrl =
  `https://form.argosidentity.com/face-auth?pid=${FACEAUTH_PROJECT_ID}` +
  `&encrypted=${encodeURIComponent(encrypted)}`;

pid and lang are not subject to encryption — append them as plaintext outside encrypted.

Definition of Request Parameters

string

required

Unique number assigned to the project when creating a FaceAuth project (automatically attached to the URL)

string

required

submission_Id approved through ID document or Knowledge-based (sid is used for distinction)

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)

string

Additional information that the administrator will assign to the user (e.g., email address, etc.)

string

Additional information that the administrator will assign to the user (same as authCf1)

string

Additional information that the administrator will assign to the user (same as authCf1)

string

Token that the administrator will add to the URL for security purposes.
Note!: This token operates separately from the pre-registered token in private mode.

How FaceAuth token works

The token is designed to assign a unique URL to each user when they authenticate through FaceAuth.
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.
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 FaceAuth guide — Token Expiration Condition Settings.

string

Display language of the FaceAuth 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.

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

Return URL

The AddOn Return URL card in the FaceAuth project settings defines where the user is sent after authentication and which fields travel with them. Selected fields are appended to the return URL query in the order shown in the settings screen.

string

The authentication result — approved or rejected. (Authentication Result in the settings screen)

string

The key of the FaceAuth submission. (Authentication ID in the settings screen) Use it as-is with the single lookup, image download, and delete APIs.

string

The user ID you passed inside encrypted on entry. (User ID in the settings screen)

string

Custom field #1 passed on entry.

string

Custom field #2 passed on entry.

string

Custom field #3 passed on entry.

Return URL example

https://yourapp.com/callback?authStatus={authStatus}&authId={authId}&authUserId={authUserId}&authCf1={authCf1}&authCf3={authCf3}

Unchecked fields are omitted from the query. The example above is what you get when custom field #2 is not selected.

Skipping the result page

Turning on Skip Result Page sends the user straight to the return URL without showing the FaceAuth result screen. The option has no effect unless a return URL is set.

Encryption

Turning on Encryption bundles the selected fields into a single encrypted parameter. Decrypt it with AES-256-ECB — the same scheme as the ID check return URL. → Encryption and decryption guide

Never treat the return URL parameters alone as proof of a successful authentication. The values travel through the user’s browser and can be tampered with. Re-check the result server-side by calling the single lookup API with authId, or use the FaceAuth webhook.

The ID check (Liveform) return URL is managed separately under the main project’s Integration Info > Return URL and passes different parameters (submissionId, kycStatus, and others). The two settings are independent. → Return URL GuideFor where to configure it in the dashboard, see FaceAuth Guide — Return URL Settings.

FaceAuth URL Validation and Error Handling

A stage-by-stage reference for the error codes raised by query string validation failures, pre-load failures, and authentication failures — and the messages users actually see.

FaceAuth API Endpoints

The base path for every endpoint is https://rest-api.argosidentity.com/v3/face-auth for US region projects and https://kr.rest-api.argosidentity.com/v3/face-auth for KR region projects.

POST /v3/face-auth

Create a FaceAuth submission

GET /v3/face-auth

List submissions

GET /v3/face-auth/{authId}

Look up a single submission

GET /v3/face-auth/{authId}/image

Download the face image

DELETE /v3/face-auth/{authId}

Delete a submission

FaceAuth Common Reference

Response object, error format, and migration

Webhooks

FaceAuth

FaceAuth webhook

Token ID expiration

Token ID expiration webhook

​How FaceAuth Is Delivered — Two Options

A. FaceAuth URL (Recommended)

B. POST /v3/face-auth API

​Query String for Accessing FaceAuth

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

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

​Definition of Request Parameters

​Return URL

​Skipping the result page

​Encryption

FaceAuth URL Validation and Error Handling

​FaceAuth API Endpoints

POST /v3/face-auth

GET /v3/face-auth

GET /v3/face-auth/{authId}

GET /v3/face-auth/{authId}/image

DELETE /v3/face-auth/{authId}

FaceAuth Common Reference

​Webhooks

FaceAuth

Token ID expiration

How FaceAuth Is Delivered — Two Options

Query String for Accessing FaceAuth

Step 1 — Prepare the plaintext (JSON) to encrypt

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

Definition of Request Parameters

Return URL

Skipping the result page

Encryption

FaceAuth API Endpoints

Webhooks