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

# 시작하기

> Add-on은 고객사의 프로젝트에서 승인된 제출 건에 대해 추가 인증을 수행하는 기능입니다. 현재는 얼굴 인증(FaceAuth)가 지원되며, 향후 신분증, 문서, 서류 등의 추가 인증 방식이 도입될 예정입니다. <br /> FaceAuth는 ID Check 인증 과정에서 승인된 유저의 셀피 사진과 FaceAuth 과정에서 획득한 셀피 사진과 비교하여 본인 여부를 한 단계 더 검증하는 절차입니다. <br /> 관리자는 Add-on을 통해 최초 신원 정보 확인 이후에도 추가적으로 해당 신원을 검증할 수 있으며, 이는 신원 확인의 신뢰도를 높입니다.

## 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를 참조하기 위해선 QueryString을 통해 URL에 추가해야 하며, 보안을 위해 항상 암호화된 상태로 사용해야 합니다.<br />
암호화는 FaceAuth 프로젝트 내의 API 키를 사용해야 하며, AES-256을 사용합니다. <br />
자세한방법은 [암호화 및 복호화 페이지의 쿼리 스트링 암호화](https://developers.argosidentity.com/ko/idcheck/getting-started/encrypt-and-decrypt-data/overview#2-쿼리-스트링-암호화데이터/)를 확인하세요.

```text Face Auth URL theme={null}
  https://form.argosidentity.com/face-auth?pid={faceAuth_projectId}
```

```text Face Auth의 QueryString에서 기본: 참조할 submission_Id만 추가 theme={null}
  https://form.argosidentity.com/face-auth?pid={faceAuth_projectId}&encrypted={sid={submission_Id}}
```

```text Face Auth의 QueryString에서 모든파라미터 추가: sid, authUserId, authCf1, authCf2, authCf3, token theme={null}
  https://form.argosidentity.com/face-auth?pid={faceAuth_projectId}&encrypted={sid={submission_Id}&authUserId={user Id}&authCf1={additional_info}&...&token={any tokenId}}
```

```text 암호화 시켰을 때 theme={null}
  https://form.argosidentity.com/face-auth?pid={faceAuth_projectId}&encrypted={encrypted}
```

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

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

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

## 애드온 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={3}>
  <Card title="Faceauth" icon="person-circle-plus" href="/ko/idcheck/add-on/add-on-webhook">
    FaceAuth 웹훅
  </Card>
</CardGroup>

## API 키

Add-on API 키는 클라이언트 및 서버 요청을 확인하고 인증하는 역할을 하며 프로젝트의 API 키와는 다릅니다. 요청자의 인증 정보를 확인하고 아르고스 아이덴티티는 요청에 따른 올바른 응답을 내려줍니다.

## 애드온 API 키 확인하기

<Steps>
  <Step title="대시보드 로그인">
    ID Check [대시보드](https://idcheck.argosidentity.com/)에 로그인합니다.
  </Step>

  <Step title="설정 메뉴 접근">
    대시보드 상단 네비게이션 바에서 `애드온` 메뉴를 클릭합니다.
  </Step>

  <Step title="프로젝트 생성">
    애드온 페이지에서 `프로젝트 생성` 버튼을 클릭 후 프록젝트를 생성합니다.

    <img height="200" src="https://mintcdn.com/argosidentity/gyvtEs7dv5_zfdlr/images/add-ons/add_on_kor.png?fit=max&auto=format&n=gyvtEs7dv5_zfdlr&q=85&s=85865110351eb2de20fd84b32e2f72ad" data-path="images/add-ons/add_on_kor.png" />
  </Step>

  <Step title="API 키 확인">
    프로젝트 생성 후 애드온 페이지의 `수정` 버튼을 클릭 후 `API`키 를 확인합니다.
    `API` 키 섹션을 찾아 우측 아이콘을 클릭하여 API 키를 복사하고 사용합니다.

    <img height="200" src="https://mintcdn.com/argosidentity/gyvtEs7dv5_zfdlr/images/add-ons/add_on_api_kor.png?fit=max&auto=format&n=gyvtEs7dv5_zfdlr&q=85&s=be9e865fd5f328ca4bc63524e52554e9" data-path="images/add-ons/add_on_api_kor.png" />
  </Step>
</Steps>

## 응답 HTTP 상태 코드

HTTP 응답 코드를 통해 상태를 반환합니다. 각 응답 코드는 요청에 대한 결과를 나타내며, 아래와 같은 규칙을 따릅니다:

* `2xx`  성공적인 요청
* `4xx`  클라이언트 오류
* `5xx`  서버 오류

| HTTP 상태 코드 |                                  메시지                                 |                                     설명                                    |
| :--------: | :------------------------------------------------------------------: | :-----------------------------------------------------------------------: |
|    `200`   |                                  OK                                  |                             요청이 성공적으로 처리되었습니다.                            |
|    `400`   |                    Invalid Query String parameters                   |  요청을 처리할 수 없습니다. 필수 파라미터가 누락되었거나, 파라미터 형식이 잘못되었습니다. 요청 파라미터를 다시 확인해 주세요.  |
|    `403`   | User is not authorized to access this resource with an explicit deny |                 권한이 없습니다. IP 화이트리스트에 등록되지 않은 IP에서 접근했습니다.                 |
|    `403`   |                               Forbidden                              |                     권한이 없습니다. 잘못된 API 키를 사용했을 수 있습니다.                     |
|    `413`   |                       Request Entity Too Large                       | 요청이 너무 큽니다. 서버에서 처리할 수 있는 크기를 초과한 데이터가 포함된 요청입니다. 요청 데이터를 축소해 다시 시도해 주세요. |
|    `500`   |                         Internal Server Error                        |      서버 오류가 발생했습니다. 아르고스 서버에서 문제가 발생했을 수 있습니다. 이 경우 아르고스 팀에 문의해 주세요.      |
|    `502`   |                              Bad Gateway                             |       서버가 업스트림 서버로부터 잘못된 응답을 받았습니다. 잠시 후 다시 시도하거나, 아르고스 팀에 문의해 주세요.       |