FaceAuth 시작하기 - ARGOS Identity

FaceAuth API가 /v3/face-auth로 개편되었습니다.구 엔드포인트 /v3/faceauth와 path·응답 구조·필드 이름·오류 형식이 모두 다릅니다. 기존 연동을 옮기려면 FaceAuth 공통 참조 — 구 API에서 옮기기를 확인하세요. Face Auth URL 방식(https://form.argosidentity.com/face-auth)은 이번 변경의 영향을 받지 않습니다.

함께 볼 문서

대시보드에서 FaceAuth 프로젝트를 만들고 정책(임계값·라이브니스·가림)과 토큰 만료를 설정하는 방법 → FACE AUTH 가이드
애드온 공통 사항(API 키 발급, 요청 할당량, 응답 HTTP 상태 코드) → 애드온 시작하기

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

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

A. Face Auth URL (권장)

ARGOS가 호스팅하는 페이지(Liveform과 유사)에서 셀피를 촬영합니다. 고객사가 카메라 UI를 직접 구현할 필요가 없으며, 프로젝트 정책에서 라이브니스(Passive/Active) 와 가림(마스크/헬멧) 차단 옵션을 활성화할 수 있습니다.

B. POST /v3/face-auth API

고객사 앱에서 카메라 UI를 직접 구현하고 촬영한 faceImage 파일을 API로 전송합니다. Active Liveness가 지원되지 않습니다 — 단순 얼굴 유사도만 비교됩니다.

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

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

FaceAuth에 접근하기 위한 QueryString

FaceAuth는 ID check의 하위 프로젝트로서 관리자는 원하는 만큼의 프로젝트를 생성할 수 있고, FaceAuth URL 방식으로 유저가 추가 인증을 받기 위해선 Add-on 프로젝트 내의 Face Auth URL을 사용합니다.
셀피 사진이 존재하는 ID document나 Knowledge-based에서 승인 받은 submission_Id를 참조하기 위해선 encrypted 쿼리 파라미터로 URL에 추가해야 하며, 보안을 위해 항상 암호화된 상태로 사용해야 합니다.
암호화는 FaceAuth 프로젝트 내의 API 키를 사용해야 하며, AES-256을 사용합니다.
자세한 방법은 쿼리 스트링 암호화를 확인하세요.

암호화 대상 평문은 JSON입니다 — 쿼리 스트링 형식이 아닙니다.sid=...&authUserId=... 처럼 key=value를 &로 이어붙인 문자열을 암호화하면 sid가 인식되지 않아 인증이 시작되지 않습니다. JSON 객체를 직렬화(JSON.stringify)한 문자열을 암호화해서 encrypted 값으로 사용하세요.이 경우 오류 코드 페이지가 아니라 “페이지를 찾을 수 없습니다” 화면이 표시되어 원인을 알기 어렵습니다. 증상별 확인 순서는 Face Auth URL 검증 및 에러 처리를 참고하세요.

쿼리 스트링 없이는 Face Auth가 실행되지 않습니다.pid만 붙인 URL로는 인증이 시작되지 않으며, 참조할 sid를 암호화해 encrypted에 담아 전달해야 합니다. 누락 시 PV-40015 오류 페이지로 이동합니다.

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

{
  "sid": "{submission_Id}"
}

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

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

Face Auth URL 구조 (이 형태만으로는 실행되지 않음)

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

암호화된 값을 encrypted에 담은 형태 (실행되는 형태)

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

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

Node.js 전체 예시

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)}`;

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

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

string

필수

FaceAuth 프로젝트 생성 시, 부여되는 프로젝트의 고유 번호 (URL에 자동적으로 붙여서 나옵니다.)

string

필수

ID document나 Knowledge-based를 통해서 승인 받은 submission_Id. (구분을 위해서 sid를 사용합니다.)

string

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

string

관리자가 추가로 부여할 해당 유저의 추가 정보들 (예: email 주소 등등)

string

관리자가 추가로 부여할 해당 유저의 추가 정보들 (authCf1과 동일)

string

관리자가 추가로 부여할 해당 유저의 추가 정보들 (authCf1과 동일)

string

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

FaceAuth token의 작동방식

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

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

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

string

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

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

리턴 URL

FaceAuth 프로젝트 설정의 AddOn Return URL 카드에서 인증 종료 후 사용자가 돌아갈 URL과 함께 전달할 필드를 지정합니다. 선택한 필드는 설정 화면에 표시된 순서대로 리턴 URL 쿼리에 붙습니다.

string

인증 결과입니다. approved, rejected 중 하나입니다. (설정 화면의 Authentication Result)

string

FaceAuth submission의 키값입니다. (설정 화면의 Authentication ID) 단건 조회·이미지 다운로드·삭제 API에 그대로 사용합니다.

string

진입 시 encrypted에 담아 전달한 유저 ID입니다. (설정 화면의 User ID)

string

진입 시 전달한 커스텀 필드 #1입니다.

string

진입 시 전달한 커스텀 필드 #2입니다.

string

진입 시 전달한 커스텀 필드 #3입니다.

리턴 URL 예시

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

체크하지 않은 필드는 쿼리에서 빠집니다. 위 예시는 커스텀 필드 #2를 선택하지 않은 경우입니다.

결과 페이지 건너뛰기

Skip Result Page를 켜면 FaceAuth 결과 화면을 표시하지 않고 곧바로 리턴 URL로 이동합니다. 리턴 URL을 입력하지 않으면 이 옵션은 동작하지 않습니다.

암호화

Encryption을 켜면 선택한 필드가 encrypted 파라미터 하나로 묶여 전달됩니다. 복호화는 AES-256-ECB로 수행하며, ID Check 리턴 URL과 같은 방식입니다. → 암·복호화 가이드

리턴 URL 파라미터만으로 인증 성공을 판정하지 마세요. 값이 사용자 브라우저를 거쳐 전달되므로 위·변조될 수 있습니다. authId로 단건 조회 API를 호출해 서버에서 결과를 재확인하거나 FaceAuth 웹훅을 사용하세요.

ID Check(라이브폼)의 리턴 URL은 본 프로젝트의 연동 정보 > 리턴 URL에서 별도로 관리되며 전달 파라미터(submissionId·kycStatus 등)도 다릅니다. 두 설정은 서로 독립적입니다. → 리턴 URL 가이드대시보드 설정 위치는 FACE AUTH 가이드 — 리턴 URL 설정을 참고하세요.

Face Auth URL 검증 및 에러 처리

QueryString 검증 실패, 사전 로드 실패, 인증 실패 시 발생하는 에러 코드와 사용자에게 실제로 노출되는 문구를 단계별로 확인하세요.

FaceAuth API 엔드포인트

모든 endpoint의 base path는 https://rest-api.argosidentity.com/v3/face-auth입니다.

POST /v3/face-auth

FaceAuth 제출 생성

GET /v3/face-auth

제출 목록 조회

GET /v3/face-auth/{authId}

제출 단건 조회

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

얼굴 이미지 다운로드

DELETE /v3/face-auth/{authId}

제출 삭제

FaceAuth 공통 참조

응답 객체·오류 형식·구 API 마이그레이션

웹훅

Faceauth

FaceAuth 웹훅

Token ID 만료

Token ID 만료 웹훅

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

A. Face Auth URL (권장)

B. POST /v3/face-auth API

​FaceAuth에 접근하기 위한 QueryString

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

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

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

​리턴 URL

​결과 페이지 건너뛰기

​암호화

Face Auth URL 검증 및 에러 처리

​FaceAuth API 엔드포인트

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 공통 참조

​웹훅

Faceauth

Token ID 만료

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

FaceAuth에 접근하기 위한 QueryString

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

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

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

리턴 URL

결과 페이지 건너뛰기

암호화

FaceAuth API 엔드포인트

웹훅