> ## 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 시작하기

> FaceAuth는 ID Check 인증 과정에서 승인된 유저의 셀피 사진과 FaceAuth 과정에서 획득한 셀피 사진을 비교하여 본인 여부를 한 단계 더 검증하는 절차입니다. 제공 방식(URL / API), Face Auth URL의 QueryString 구조, 요청 파라미터 정의를 다룹니다.

<Info>
  **함께 볼 문서**

  * 대시보드에서 FaceAuth 프로젝트를 만들고 정책(임계값·라이브니스·가림)과 토큰 만료를 설정하는 방법 → [FACE AUTH 가이드](/dashboard/ko/face-auth-guide)
  * 애드온 공통 사항(API 키 발급, 요청 할당량, 응답 HTTP 상태 코드) → [애드온 시작하기](/ko/idcheck/add-on/overview)
</Info>

## FaceAuth 진행 방식 — 2가지 선택지

FaceAuth는 다음 두 가지 방식으로 제공할 수 있습니다. **별도 카메라 UI 구현 없이 Active Liveness까지 활용할 수 있는 Face Auth URL 방식을 권장합니다.**

<CardGroup cols={2}>
  <Card title="A. Face Auth URL (권장)" icon="link" href="/dashboard/ko/face-auth-guide">
    ARGOS가 호스팅하는 페이지(Liveform과 유사)에서 셀피를 촬영합니다. 고객사가 카메라 UI를 직접 구현할 필요가 없으며, 프로젝트 정책에서 **라이브니스(Passive/Active)** 와 가림(마스크/헬멧) 차단 옵션을 활성화할 수 있습니다.
  </Card>

  <Card title="B. POST /faceauth API" icon="code" href="/ko/idcheck/add-on/post-faceauth">
    고객사 앱에서 카메라 UI를 직접 구현하고 촬영한 `faceImage` 파일을 API로 전송합니다. **Active Liveness가 지원되지 않습니다** — 단순 얼굴 유사도만 비교됩니다.
  </Card>
</CardGroup>

<Tip>
  **휴대폰 화면 재생·사진 캡쳐 등 스푸핑 시도가 우려된다면 URL 방식을 사용하세요.** POST API 방식은 전달된 이미지 한 장만 유사도로 판정하므로 실제 촬영 여부를 검증하지 못합니다. URL 방식은 프로젝트 정책에서 **라이브니스 임계값** 을 설정하여 화면 재생·정지 사진 등의 스푸핑을 차단할 수 있습니다.
</Tip>

대시보드에서 정책(임계값·라이브니스·가림)을 설정하는 방법과 두 방식의 활용 사례는 [FACE AUTH 가이드](/dashboard/ko/face-auth-guide)에서 확인하세요. 이 문서의 나머지 섹션은 **A. Face Auth URL 방식**의 파라미터와 인증 흐름을 다룹니다. **B. POST API 방식**은 [POST/Faceauth](/ko/idcheck/add-on/post-faceauth) 페이지를 참고하세요.

## FaceAuth에 접근하기 위한 QueryString

FaceAuth는 ID check의 하위 프로젝트로서 관리자는 원하는 만큼의 프로젝트를 생성할 수 있고, FaceAuth URL 방식으로 유저가 추가 인증을 받기 위해선 **Add-on 프로젝트 내의 Face Auth URL을 사용합니다.** <br />
셀피 사진이 존재하는 ID document나 Knowledge-based에서 승인 받은 submission\_Id를 참조하기 위해선 `encrypted` 쿼리 파라미터로 URL에 추가해야 하며, 보안을 위해 항상 암호화된 상태로 사용해야 합니다.<br />
암호화는 FaceAuth 프로젝트 내의 API 키를 사용해야 하며, AES-256을 사용합니다. <br />
자세한 방법은 [쿼리 스트링 암호화](/ko/idcheck/getting-started/encrypt-and-decrypt-data/overview#2-쿼리-스트링-암호화)를 확인하세요.

<Warning>
  **암호화 대상 평문은 JSON입니다 — 쿼리 스트링 형식이 아닙니다.**

  `sid=...&authUserId=...` 처럼 `key=value`를 `&`로 이어붙인 문자열을 암호화하면 `sid`가 인식되지 않아 인증이 시작되지 않습니다. **JSON 객체를 직렬화(`JSON.stringify`)한 문자열을 암호화**해서 `encrypted` 값으로 사용하세요.

  이 경우 오류 코드 페이지가 아니라 **"페이지를 찾을 수 없습니다" 화면**이 표시되어 원인을 알기 어렵습니다. 증상별 확인 순서는 [Face Auth URL 검증 및 에러 처리](/ko/idcheck/add-on/faceauth-url-errors#2-1-필수-파라미터-누락)를 참고하세요.
</Warning>

<Warning>
  **쿼리 스트링 없이는 Face Auth가 실행되지 않습니다.**

  `pid`만 붙인 URL로는 인증이 시작되지 않으며, 참조할 `sid`를 암호화해 `encrypted`에 담아 전달해야 합니다. 누락 시 [`PV-40015` 오류 페이지](/ko/idcheck/add-on/faceauth-url-errors#2-진입-단계-검증-실패)로 이동합니다.
</Warning>

### 1단계 — 암호화할 평문(JSON) 준비

<CodeGroup>
  ```json 기본: 참조할 submission_Id만 포함 (최소 실행 형태) theme={null}
  {
    "sid": "{submission_Id}"
  }
  ```

  ```json 모든 파라미터 포함: 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>

### 2단계 — FaceAuth 프로젝트 API 키로 AES-256 암호화 후 URL 조립

```text Face Auth URL 구조 (이 형태만으로는 실행되지 않음) theme={null}
  https://form.argosidentity.com/face-auth?pid={faceAuth_projectId}
```

```text 암호화된 값을 encrypted에 담은 형태 (실행되는 형태) theme={null}
  https://form.argosidentity.com/face-auth?pid={faceAuth_projectId}&encrypted={encrypted}
```

<Warning>
  **`encrypted` 값은 반드시 URL 인코딩해야 합니다.**

  AES-256 암호화 결과(Base64)에는 `+`, `/`, `=` 문자가 포함됩니다. 인코딩 없이 URL에 붙이면 `+`가 공백으로 해석되어 **복호화 자체가 실패**하고 `sid`를 읽을 수 없습니다. `encodeURIComponent`(또는 각 언어의 URL 인코딩 함수)를 적용하세요.
</Warning>

```javascript Node.js 전체 예시 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');
}

// 1단계: 평문은 JSON 객체를 직렬화한 문자열
const queryData = JSON.stringify({
  sid: 'submission_12345',
  authUserId: 'user123',
});

// 2단계: FaceAuth 프로젝트의 API 키로 암호화 후 URL 인코딩
const encrypted = encrypt(queryData, FACEAUTH_API_KEY);
const faceAuthUrl =
  `https://form.argosidentity.com/face-auth?pid=${FACEAUTH_PROJECT_ID}` +
  `&encrypted=${encodeURIComponent(encrypted)}`;
```

<Note>
  `pid`와 `lang`은 암호화 대상이 아니며 `encrypted` 밖에 평문으로 붙입니다.
</Note>

## 요청 파라미터들에 대한 정의

<ResponseField name="pid" type="string" required>
  FaceAuth 프로젝트 생성 시, 부여되는 프로젝트의 고유 번호 (URL에 자동적으로 붙여서 나옵니다.)
</ResponseField>

<ResponseField name="sid" type="string" required>
  ID document나 Knowledge-based를 통해서 승인 받은 submission\_Id. (구분을 위해서 sid를 사용합니다.)
</ResponseField>

<ResponseField name="authUserId" type="string">
  관리자가 부여할 해당 유저의 유저 Id (관리자 서비스 내의 유저 Id가 될 수도 있고, ID document나 Knowledge-based에서 사용한 userId와 동일하게 부여할 수도 있습니다.)
</ResponseField>

<ResponseField name="authCf1" type="string">
  관리자가 추가로 부여할 해당 유저의 추가 정보들 (예: email 주소 등등)
</ResponseField>

<ResponseField name="authCf2" type="string">
  관리자가 추가로 부여할 해당 유저의 추가 정보들 (authCf1과 동일)
</ResponseField>

<ResponseField name="authCf3" type="string">
  관리자가 추가로 부여할 해당 유저의 추가 정보들 (authCf1과 동일)
</ResponseField>

<ResponseField name="token" type="string">
  보안을 위해서 관리자가 해당 url에 추가할 token 입니다. <br />
  **주의사항!**: 해당 token은 프라이빗 모드의 사전등록 token과는 별개로 작동됩니다.

  <Accordion title="FaceAuth token의 작동방식">
    Token은 사용자가 FaceAuth를 통해 인증할 때, 각 사용자에게 고유한 URL을 부여하기 위해 설계되었습니다. <br />
    Token을 적용하려면 FaceAuth 프로젝트에서 토큰 만료 조건 설정 옵션을 활성화해야 하며, 다음과 같은 방식으로 동작합니다.

    * 횟수 기반 만료: 토큰이 한 번 사용되면 해당 Token ID가 즉시 만료 처리됩니다.
    * 시간 기반 만료: 토큰이 한 번 사용된 시점을 기준으로 시간이 경과하면 해당 Token ID가 만료 처리됩니다.

    이 토큰은 메인 프로젝트의 프라이빗 모드 토큰이나 사전 등록 토큰과는 별개로 동작합니다. <br />
    예를 들어, token에는 관리자가 설정한 임의의 tokenId를 지정할 수 있고, 메인 프로젝트에서 사용한 token을 재사용 하더라도 별개로 보기 때문에 작동됩니다.
    FaceAuth 프로젝트에서 토큰 만료 조건 설정 옵션을 활성화에 대한 가이드는 [FACE AUTH 가이드 — 토큰 만료 조건 설정](/dashboard/ko/face-auth-guide#토큰-만료-조건-설정)을 참고하세요.
  </Accordion>
</ResponseField>

<ResponseField name="lang" type="string">
  Face Auth 화면의 표시 언어입니다. ISO 639-1 소문자 코드를 사용합니다 (예: `en`, `ko`). **암호화 대상이 아니며 `encrypted` 밖에 평문으로 붙입니다** (예: `?pid={faceAuth_projectId}&encrypted={encrypted}&lang=en`). 미설정 시 모바일은 기기 설정 언어, PC는 브라우저 언어를 따릅니다. 지원 언어 목록은 [라이브폼 지원 언어](/ko/idcheck/getting-started/liveform-languages)를 참고하세요.
</ResponseField>

<Note>
  승인된 건 중, 셀피 사진이 존재하지 않는 경우에는 신분증의 초상화 이미지를 대신 사용합니다.
</Note>

<Card title="Face Auth URL 검증 및 에러 처리" icon="triangle-exclamation" href="/ko/idcheck/add-on/faceauth-url-errors">
  QueryString 검증 실패, 사전 로드 실패, 인증 실패 시 발생하는 에러 코드와 사용자에게 실제로 노출되는 문구를 단계별로 확인하세요.
</Card>

## FaceAuth API 엔드포인트

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

  <Card title="GET/FaceAuth" icon="person-circle-check" href="/ko/idcheck/add-on/get-faceauth">
    Faceauth 조회
  </Card>

  <Card title="GET/FaceAuth/Image" icon="person-circle-check" href="/ko/idcheck/add-on/get-faceauth_image">
    FaceAuth 이미지 조회
  </Card>

  <Card title="DELETE/FaceAuth" icon="person-circle-xmark" href="/ko/idcheck/add-on/delete-faceauth">
    Faceauth 삭제
  </Card>
</CardGroup>

## 웹훅

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

  <Card title="Token ID 만료" icon="clock" href="/ko/idcheck/add-on/add-on-webhook-token">
    Token ID 만료 웹훅
  </Card>
</CardGroup>