메인 콘텐츠로 건너뛰기

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.

FACE AUTH는 기존 eKYC에서 확보한 Submission ID의 셀피(Reference)와 사용자의 최신 셀피(Target)를 비교해 동일인 여부를 즉시 확인하는 애드온 서비스입니다. 별도의 복잡한 과정 없이 셀피 한 번으로 재인증을 완료할 수 있습니다.

​
대표 활용 시나리오

비밀번호나 인증코드 없이 셀피 한 번으로 신원을 재확인하므로, 보안을 강화하면서도 사용자 마찰을 낮출 수 있습니다.

단말기 변경

금융기관에서 기기 변경·번호 변경 시 계정 도용 위험을 낮추기 위한 재인증 수단으로 사용합니다.

이상징후 감지 시 재인증

ATO 방지 - 고위험 로그인, 해외 접속, 대량 시도 탐지 시 추가 얼굴 인증으로 접근 차단/해제 정책을 적용합니다.

정기 본인 재확인

주기적 KYC Refresh - 고가치 서비스·규제 산업에서 주기적 동일인 확인 절차로 활용합니다.

비밀번호 분실/정보 변경

비밀번호 재설정, 결제수단·연락처 변경 등 중요 계정 변경 전 본인 확인 단계로 삽입합니다.

​
동작 방식 (3-Step)

1

전제조건

eKYC의 승인된 Submission이 존재해야 합니다. (Reference)
2

진행

Add-On URL 호출 (pid + Submission ID 포함) → 셀피 촬영
데스크톱 진입 시 QR 표시 → 모바일로 이어받아 촬영합니다.
3

판정/저장

등록본 vs 검증본 자동 비교 → 결과는 Auth ID(제출건)로 대시보드에 저장됩니다.
핵심 체크
  • 승인된 Submission ID가 존재해야 합니다. (Reference)
  • FACE AUTH URL 사용 시 보안을 위해 암호화하여 사용해야 합니다.
  • 임계값·라이브니스·가림(마스크/헬멧/모자 등) 정책은 프로젝트 옵션으로 제어할 수 있습니다.

​
FACE AUTH의 장점

장점설명
빠른 재인증신분증 재촬영 없이 셀피 한 번으로 완료
보안 보강비밀번호·OTP와 병행하는 추가 요인으로 계정 보호
정책 유연성얼굴 일치 임계값, 라이브니스, 가림 차단 등 상황별 세분화 설정
간단한 연동기존 eKYC 프로젝트에 애드온 형태로 종속되어 운영 일관성 유지

​
프로젝트 생성 및 설정

FACE AUTH를 사용하려면 먼저 대시보드에서 Add-On 프로젝트를 만들고 정책(임계값·라이브니스·가림)을 설정합니다.

​
Step 1: Add-On 프로젝트 만들기

대시보드의 **애드온 메뉴 → ‘프로젝트 생성하기’**를 선택해 새 FACE AUTH 프로젝트를 만듭니다. 생성 즉시 eKYC 프로젝트와 종속 연결이 형성되며, Add-On URL과 API 키가 자동 매핑됩니다. 
경로: 대시보드 > 애드온 > 프로젝트 생성하기
Add-On 프로젝트 생성 화면
Add-On 프로젝트 생성 화면

​
Step 2: 프로젝트 정보 설정

설정 화면에서 프로젝트명·로고를 지정하고, 인증 제출 완료 후 이동할 버튼/URL을 설정합니다.
Add-On 프로젝트 생성 화면
설정 항목설명
Project Name인증 시작화면에 제목으로 표시됩니다
Project StatusService(정상 운영) / Closed(인증 불가)
Add on Logo첫 번째 인증 화면 상단에 표시 (미설정 시 ARGOS 로고 표시)
Return URL인증 완료 후 사용자가 리디렉션되는 URL

​
Step 3: 정책 (임계값) 설정

임계값은 낮을수록 완화, 높을수록 엄격합니다. 서비스 리스크·UX 목표에 맞춰 단계적으로 조정하세요.
Add-On 프로젝트 생성 화면
정책 항목설명권장값
얼굴 인증 임계값eKYC 승인자의 얼굴과 동일인 여부 판단 기준98점
라이브니스촬영 셀피가 실제 살아있는 사람인지 판단 (Passive/Active)70점
얼굴 가려짐인증 중 얼굴이 다른 물체로 가려지지 않았는지 확인-
얼굴 가려짐과 얼굴 가림 임계점은 동시에 사용할 수 없습니다.
특수 환경 옵션:
  • 머리 가림 임계점: 안전모 착용이 필요한 환경 (바이크, 건설 현장 등)
  • 얼굴 가림 임계점: 마스크 착용이 필요한 환경 (병원, 건설 현장 등)

​
Step 4: Add-On URL 파라미터 및 암호화 설정

FACE AUTH URL을 사용하기 위해서는 필수 파라미터를 등록해야 합니다. 필수 파라미터:
파라미터설명
pidAdd-On 프로젝트 ID (URL 경로/파라미터에 포함)
sideKYC Submission ID (승인 상태에서만 Add-On 인증가능, 암호화 필요)
URL 패턴 예시: 
...?pid={ADDON_PID}&encrypted={encrypted}
encrypted 문장에서 Submission ID는 sid, Token ID는 token으로 표시해서 사용합니다.

​
토큰 만료 조건 설정

Token ID를 통하여 제한된 접근 제어를 구성할 수 있습니다.
Add-On 프로젝트 생성 화면
만료 조건설명
횟수 기반 만료토큰이 1회 사용 시 해당 Token ID를 만료 처리
시간 기반 만료토큰이 1회 사용된 기점으로 시간을 측정하여 Token ID를 만료 처리
만료 트리거링 조건은 FACE AUTH 첫 화면에서 “시작하기” 버튼이 클릭되었을 때입니다.

​
사용자에게 제공하기

FACE AUTH는 두 가지 방식으로 제공할 수 있습니다.
사용자에게 Add-On URL을 열도록 안내하면 웹 화면에서 셀피 촬영으로 재인증을 진행합니다.필수 파라미터:
  • pid={AddOn Project ID} — URL 쿼리스트링에 평문으로 포함
  • encrypted={...} — 내부에 sid={승인된 eKYC Submission ID} 포함, AES-256으로 암호화 필수 (Step 4 참고)
URL 패턴
https://form.argosidentity.com/face-auth?pid={ADDON_PID}&encrypted={encrypted}
데스크톱 → 모바일 전환: PC에서 열면 QR 코드가 표시되어 사용자가 휴대폰으로 스캔 후 촬영을 이어갑니다.
체크리스트
  • ✅ 링크/버튼에 Add-On URL 연결
  • ✅ sid가 누락/미승인이 아닌지 확인 (eKYC가 approved 상태여야 함)
  • ✅ sid 등 보안 파라미터는 반드시 encrypted 내부에 포함되어야 함 (평문 노출 금지)
  • ✅ 데스크톱 유입이 많다면 QR 전환 안내 문구를 상단 고정 배치

​
동작 확인 (스모크 테스트)

  • 승인된 submissionId로 Add-On URL 호출 시 인증 화면이 나타나는지
  • PC 진입 시 QR 노출 및 모바일 전환이 자연스러운지
  • 촬영 후 결과가 Add-On 제출건(Auth ID)으로 저장·조회되는지
Add-On 프로젝트 생성 화면

​
AUTH ID - 인증 결과 확인

Auth ID는 FACE AUTH(애드온) 한 건의 결과(제출건)를 지칭합니다. 등록본(이전에 eKYC로 승인된 얼굴)과 이번 셀피(검증본)를 비교한 동일인 판정, 적용된 정책 스냅샷, 처리 타임라인이 함께 기록됩니다.

​
대시보드에서 결과 확인

대시보드 > 애드온(FACE AUTH) 프로젝트 > 제출건(Auth ID) 목록 > 상세 보기
목록 화면에서 확인 가능한 정보:
  • 시간
  • AUTH ID (TARGET)
  • Submission ID (Reference)
  • Status
상세 화면에서 확인 가능한 정보:
  • 정책 스냅샷
  • 점수/임계값
  • 라이브니스·가림 결과
  • 비교 이미지
  • 로그
Add-On 프로젝트의 Auth ID 대시보드

​
Auth ID 상세 정보

필드설명
Authentication ID해당 제출건의 고유 식별자
Submission ID제출 시 비교대상으로 참조한 기 승인된 제출건
StatusApproved, Rejected로 인증에 대한 결과 표시
Policy해당 제출건이 진행될 때 적용된 프로젝트 옵션
FACE Similarity인증 시 측정된 셀피 이미지 간의 유사도
Liveness제출된 셀피의 라이브니스 점수
Face OccludedPass / Fail로 얼굴이 가려졌는지 판단한 결과
Reference 정보에서 Selfie를 우선적으로 비교하며, Selfie가 없는 경우 신분증의 초상화를 차순으로 호출하여 비교합니다.
Add-On 프로젝트의 Auth ID 대시보드

​
웹훅으로 실시간 연동

FACE AUTH가 완료되어 최종 결과가 나오면, 기존 ID Check 프로젝트에 등록된 Webhook URL로 결과가 자동 전송됩니다. 트리거 타입: "faceAuth" 
{
  "webhook_trigger": "faceAuth",
  "Authentication_id": "AUTH_...",
  "data": {
    "Submission_id": "SUB_...",
    "Auth_Status": "approved | rejected",
    "Create_Time": "UTC+0",
    "User_id": "optional",
    "cf1": "optional",
    "cf2": "optional",
    "cf3": "optional",
    "reference": {
      "userid": "optional",
      "email": "optional",
      "cf": { "cf1": "optional", "cf2": "optional", "cf3": "optional" }
    }
  }
}
구현 체크리스트
  • ✅ Webhook URL 등록(프로젝트 단위) 및 2xx 응답으로 수신 확인
  • ✅ 중복 수신 방지 처리: Authentication_id 기준 중복 확인
  • ✅ 타임존 처리: Create_Time(UTC+0) → 필요 시 내부 표준 시각 변환
  • ✅ 키 매핑: Submission_id, User_id, cf1~3로 내부 사용자/요청과 매핑
  • ✅ 감사 로깅: 원본 페이로드와 라우팅 결과를 함께 저장
대시보드로 관리자의 운영 친화적 판독, 개발팀은 웹훅으로 시스템 자동화를 동시에 진행할 수 있습니다. Auth ID 단위로 상태·점수·정책·타임라인을 일관되게 보고, 웹훅의 Authentication_id/Submission_id로 내부 시스템 플로우에 즉시 연결하여 사용하세요.

​
빠른 도입을 위한 체크리스트

1

프로젝트 생성

대시보드 → 애드온에서 FACE AUTH 프로젝트를 생성합니다.
2

정책값 설정

얼굴 일치 임계값 / 라이브니스 / 가림 차단(ON/OFF)을 설정합니다.
3

eKYC 승인 Submission 확보

Reference로 사용할 승인된 eKYC Submission이 필요합니다.
4

호출 설계

Add-On URL에 pid + Submission ID 포함 (데스크톱→QR→모바일 흐름 고려)
5

결과 확인 루틴

대시보드에서 Auth ID(제출건) 상태·정책·비교 결과를 모니터링합니다.

​
운영 팁

  • 정책 초기값은 다소 보수적으로 시작 → 실제 서비스 데이터를 보며 임계값을 단계적으로 튜닝
  • 모니터링 지표: 재인증 성공률, 중도이탈률, 평균 인증 소요시간, 위험 이벤트 차단률, 재설정/변경 완료율
  • UX 설계: 데스크톱 진입률이 높다면 QR 전환 플로우를 분명히 안내하고, 모바일 사용자는 인증 가이드를 최소 문구로 제공

​
관련 문서

Add-On API 개요

Add-On 서비스의 전체 개요를 확인합니다.

POST/Face Auth API

API를 통한 FACE AUTH 연동 방법을 확인합니다.

FACE AUTH 웹훅

FACE AUTH 결과를 웹훅으로 수신하는 방법을 확인합니다.

암호화 가이드

URL 암호화 방법을 확인합니다.