완전한 ID check 온보딩 가이드
이 가이드는 처음으로 ID check를 서비스에 도입하는 고객사 개발자를 위해 작성되었습니다. 실제 통합 과정에서 맞닥뜨리는 고민들을 순서대로 짚어가며, 각 단계에서 ARGOS가 제공하는 기술을 안내합니다.사전 준비물
- ARGOS Identity 계정 (idcheck.argosidentity.com 가입)
- 대시보드 접속 및 API 키 확인
ID check 통합의 핵심 원리
ID check를 시스템에 통합할 때, 가장 먼저 이해해야 할 내용이 있습니다. API의 역할: ID check의 API는 ARGOS 시스템으로 들어오고 나가는 정보의 안전한 전송을 위한 파이프라인 역할을 합니다. 주요 용도는 다음과 같습니다.| 목적 | 관련 API | 설명 |
|---|---|---|
| Token 관리 | POST/GET/DELETE Token | Private mode에서 일회용 URL 생성 및 관리 |
| 데이터 획득 및 관리 | GET/PATCH/DELETE Submission, GET Image | 검증 완료된 Submission 데이터 조회, 수정, 삭제, 이미지 조회 |
| 시스템 연결 | POST Review, PUT Image | Pending 건 검수 처리, 이미지 추가/교체 등 워크플로우 연동 |
| Migration | POST Submission | 기존 KYC 데이터 이전, 특수한 상황에서 데이터 삽입, 개발 테스트 |
목차
파트 1: 기초
계정 설정, 핵심 개념 이해
파트 2: 통합
Liveform 연결, 결과 수신, 데이터 활용
파트 3: 운영
보안 강화, 테스트, 라이브 전환
파트 1: 기초
ARGOS ID check란?
ARGOS ID check는 AI 기반 신원 인증 플랫폼입니다. 사용자가 신분증을 촬영하고 셀피를 찍으면, AI가 문서 진위 여부를 분석하고 결과를 내려줍니다.문서 검증
전 세계 200+ 국가의 여권, 운전면허증, 국가 신분증, 거주 허가증 등을 검증합니다.
AI 사기 탐지
위조, 사진 대체, 문서 변조를 AI로 자동 감지합니다.
데이터 추출
신분증에서 이름, 생년월일, 국적 등의 정보를 자동 추출합니다.
KYC/AML 컴플라이언스
검증 규칙 커스터마이즈 및 감사 추적(Audit Trail)을 제공합니다.
계정 설정 및 필수 정보 확인
계정 만들기
idcheck.argosidentity.com 에서 가입하고 이메일을 인증한 뒤 대시보드에 로그인하세요.
필수 정보 확인
대시보드에서 아래 세 가지 정보를 확인하세요. 각 항목은 신규 대시보드의 프로젝트 관리 메뉴에서 확인할 수 있습니다.1. Project ID (PID) 및 Liveform URL프로젝트 관리 → 프로젝트 설정 → 프로젝트 정보 에서 확인합니다.
2. API Key프로젝트 관리 → 프로젝트 설정 → 연동 정보 에서 확인합니다.
- Project ID (PID) — 프로젝트 고유 식별자
- Liveform URL — 사용자에게 제공할 신원 인증 페이지 URL (프로젝트 파이프라인 섹션)

- API Key — API 요청 인증에 사용 (절대 외부에 노출하지 마세요)

핵심 개념
Submission (제출)
Submission (제출)
Submission은 단일 신원 인증 시도를 의미합니다. 사용자가 Liveform에서 신분증을 촬영하고 제출하면 Submission이 생성됩니다.주요 속성:
- Submission ID — 고유 식별자 (예:
sub_abc123) - KYC 상태 —
approved(승인),rejected(거절),pending(수동 심사 대기) - 추출 데이터 — 이름, 생년월일, 국적 등
- 이미지 — 신분증 사진과 셀피
- 메타데이터 — 타임스탬프, IP, 고객사가 전달한 userid/email 등
Liveform
Liveform
Liveform은 ARGOS가 호스팅하는 신원 인증 페이지입니다. 고객사는 이 URL을 사용자에게 제공하기만 하면 됩니다.쿼리 스트링 파라미터를 추가하여 사용자 정보 전달, 국가 제한, 보안 옵션 등을 커스터마이즈할 수 있습니다.
- 데스크톱: QR 코드를 표시하여 모바일로 스캔 유도
- 모바일: 바로 카메라 인터페이스로 진행
Webhook (웹훅)
Webhook (웹훅)
웹훅은 검증 이벤트가 발생할 때 고객사 서버로 실시간 HTTP POST 요청을 보내는 기능입니다. 운영 환경에서 검증 결과를 받는 가장 권장되는 방법입니다.주요 이벤트:
approved— 검증 승인rejected— 검증 거절submit— 보류(pending) 상태로 제출updated— 데이터 업데이트deleted— Submission 삭제created— Submission 생성retry— 사용자 재시도token_expired— Token 만료injection— API를 통한 데이터 주입aml— AML 검사 완료aml_monitor— AML 온고잉 모니터링 결과
Token (토큰) — Private Mode
Token (토큰) — Private Mode
Token을 사용하면 Liveform URL을 일회용으로 만들 수 있습니다 (Private Mode).용도:
- 동일한 URL이 여러 사람에게 공유되는 것 방지
- 특정 사용자에게만 유효한 인증 링크 제공
- 보안이 중요한 서비스(금융, 의료 등)에서 사용
- 서버에서 고유한 tokenId를 생성하여 ARGOS에 등록
token파라미터를 Liveform URL에 추가하여 사용자에게 전달- 최초 사용 후 3분 또는 제출이 결정 상태에 도달하면 만료
Return URL
Return URL
Return URL은 사용자가 인증을 완료하고 “OK” 버튼을 누르거나 5초 후, 고객사 앱으로 돌아올 URL입니다.대시보드에서 설정하며, KYC 상태(
kycStatus), 이메일, userid, 커스텀 필드 등이 쿼리 파라미터로 함께 전달됩니다.예시:Return URL은 사용자 경험(UX) 흐름을 위한 것입니다. 검증 결과의 공식 수신 채널로는 웹훅을 사용하세요.
쿼리 스트링 및 암호화
쿼리 스트링 및 암호화
쿼리 스트링으로 Liveform 동작을 커스터마이즈할 수 있습니다:
email,userid,cf1~cf3— 사용자 정보 미리 입력blacklistCountries=false,ageLimit=false— 정책 일시 해제
allowedCountries— 허용 국가 제한allowedIdTypes— 허용 문서 유형 제한selectedIssuingCountry,selectedIdType— 선택 화면 건너뛰기token— Private mode 토큰
- AES-256-ECB — 빠르고 간단한 블록 암호화 방식
- AES-256-GCM — 인증 및 무결성 기능을 포함한 강화된 암호화 방식
- API 키 — 프로젝트에 부여된 기본 API 키
- Custom secretKey — 대시보드에서 별도로 발급받아 사용하는 전용 키 (발급 후 한 번만 표시되므로 분실 시 재발급 필요)
파트 2: 통합
고객사 개발자가 실제로 직면하는 고민들을 단계별로 해결합니다.Q1. “어떻게 내 앱에서 사용자에게 신원 인증을 시키나?”
답: Liveform URL을 사용자에게 전달하세요. 대시보드에서 Liveform URL을 복사하여 버튼 링크, 리디렉션, 이메일 링크 등 어떤 방식으로든 사용자에게 전달하면 됩니다.Q2. “내 서비스의 사용자 정보를 미리 전달할 수 있나?”
답: 쿼리 스트링 파라미터를 URL에 추가하세요. 사용자가 이미 회원 가입을 한 상태라면, 이메일·사용자 ID 등을 미리 넣어주면 사용자가 Liveform에서 다시 입력하지 않아도 됩니다. 또한 이 값들은 Submission 데이터와 함께 저장되어 나중에 웹훅이나 GET Submission API로 조회할 때 활용할 수 있습니다. 주요 파라미터:| 파라미터 | 설명 | 예시 |
|---|---|---|
email | 사용자 이메일 | user@example.com |
userid | 내부 사용자 ID | user_12345 |
cf1, cf2, cf3 | 커스텀 메타데이터 (예: 캠페인 ID, 서비스 구분) | campaign_summer |
sid | Submission ID (업데이트 시 사용) | sub_abc123 |
Q3. “URL이 여러 사람에게 공유되는 게 우려된다”
답: Token을 등록하여 Private Mode (일회용 URL)를 사용하세요. Token을 Liveform URL에 추가하면, 해당 URL은 일회용이 됩니다. 최초 사용 후 3분이 지나거나 인증이 완료되면 더 이상 사용할 수 없습니다.
더 알아보기: POST Token API | 쿼리 스트링 및 토큰 가이드
Q4. “특정 국가 또는 문서 유형만 허용하고 싶다”
답: 암호화된 쿼리 스트링 파라미터를 사용하세요.allowedCountries, allowedIdTypes 등 보안이 필요한 파라미터는 암호화하여 encrypted 파라미터에 담아야 합니다. 암호화 모듈은 AES-256-ECB 또는 AES-256-GCM 중 선택할 수 있으며, 암호화 키는 프로젝트 API 키 또는 대시보드에서 별도 발급한 Custom secretKey를 사용할 수 있습니다.

| 파라미터 | 설명 |
|---|---|
allowedCountries | 허용할 국가 (ISO Alpha-3 코드, 쉼표 구분) |
allowedIdTypes | 허용할 문서 유형 |
selectedIssuingCountry | 국가 선택 화면을 건너뛰고 지정 |
selectedIdType | 문서 유형 선택 화면을 건너뛰고 지정 (반드시 selectedIssuingCountry와 함께 사용) |
projectionId / projectionName | 특정 필드를 제외하는 Projection 적용 |
auxidField | 추가 신원 검증 (예: 전화번호 SMS 인증) |
Q5. “인증 완료 후 사용자를 내 앱으로 돌려보내고 싶다”
답: 대시보드에서 Return URL을 설정하세요. 사용자가 인증을 마치고 “OK”를 누르면 설정한 URL로 리디렉션됩니다. KYC 결과가 쿼리 파라미터로 함께 전달됩니다.
더 알아보기: Return URL 가이드
Q6. “인증 결과를 실시간으로 서버에서 받고 싶다”
답: 웹훅(Webhook)을 설정하세요. 웹훅은 인증 이벤트가 발생할 때 고객사 서버로 즉시 HTTP POST 요청을 보내는 기능입니다. 이 방법이 인증 결과를 수신하는 가장 안정적이고 권장되는 방법입니다.대시보드에서 웹훅 URL 등록
프로젝트 관리 → 프로젝트 설정 → 연동 정보의 웹훅 설정 섹션에서 엔드포인트 URL을 입력하세요:

웹훅 URL은 반드시 HTTPS를 사용해야 합니다. 로컬 개발 시에는 ngrok 또는 webhook.site를 사용하여 테스트하세요.
웹훅 이벤트 확인
전체 이벤트 유형:
더 알아보기: 웹훅 이벤트 상세 가이드
| 이벤트 | 설명 | 활용 예시 |
|---|---|---|
approved | 검증 승인 | 사용자 상태 업데이트, 서비스 이용 허가 |
rejected | 검증 거절 | 사용자 알림, 재제출 요청 |
submit | 보류(pending) 상태 | 관리자 알림, 수동 심사 요청 |
updated | 데이터 업데이트 | DB 동기화 |
deleted | Submission 삭제 | 관련 데이터 정리 |
created | Submission 생성 | 인증 시작 추적 |
retry | 사용자 재시도 | 재시도 패턴 모니터링 |
token_expired | Token 만료 | 새 Token 발급 |
injection | API를 통한 데이터 주입(Injection) | API 작업 로깅 |
aml | AML 검사 완료 | 컴플라이언스 결과 처리 |
aml_monitor | AML 온고잉 모니터링 결과 | 지속적 모니터링 처리 |
Q7. “인증 데이터를 우리 DB/시스템과 연동하고 싶다”
답: GET Submission API로 검증 데이터를 조회하세요. 웹훅으로 실시간 수신도 가능하지만, 필요한 시점에 직접 특정 Submission의 데이터를 조회하고 싶을 때 GET Submission API를 사용합니다.| 파라미터 | 설명 |
|---|---|
submission_id | 특정 제출 건의 고유 ID로 단일 조회 |
userid | 사용자 ID와 일치하는 모든 제출 건 조회 |
email | 이메일과 일치하는 모든 제출 건 조회 |
count | 반환할 결과 수 (기본값: 50) |
start_date / end_date | 조회 기간 필터 (YYYY-MM-DD) |
request_type | 특정 데이터 유형만 조회 (kyc, aml, data, others) |
| API | 용도 |
|---|---|
PATCH /submission | Submission 데이터 수정 (kycStatus, fullName, email 등) |
DELETE /submission | Submission 전체 삭제 (GDPR 등 개인정보 삭제 요청 대응) |
DELETE /submission/partial | 이미지만 삭제 (메타데이터 유지) |
GET /image | Submission에 저장된 이미지(신분증, 셀피 등) 조회 |
PUT /image | 기존 Submission에 이미지 추가 또는 교체 (Base64 인코딩) |
POST /submission/review | Pending 상태의 Submission을 API로 승인/거절 처리 (수동 심사 자동화) |
POST /submission/review 는 프로젝트 설정에서 검토자가 ‘Client’로 설정된 경우, 고객사가 API를 통해 직접 pending 건을 심사할 수 있게 해줍니다. 이미 승인/거절된 건은 수정할 수 없습니다.Q8. “기존에 보유한 KYC 데이터를 ARGOS에 이전하고 싶다”
답: POST Submission API (Migration)를 사용하세요. 이 API는 다음과 같은 상황에서 사용합니다:- 데이터 마이그레이션: 기존 시스템의 KYC 완료 데이터를 ARGOS 대시보드로 이전
- 특수한 상황: ID Check 검증을 거치기 어려운 예외적 케이스에서 직접 데이터 삽입
- 개발 및 테스트: 개발 단계에서 다양한 시나리오를 테스트할 때 활용
| 필드 | 설명 |
|---|---|
admin | 프로젝트 관리자 이메일 (대시보드에 등록되어 있어야 함) |
email | KYC 제출자의 이메일 주소 |
fullName | 제출자의 전체 이름 |
birthDate | 생년월일 (YYYY-MM-DD) |
kycStatus | approved 또는 rejected |
idType, issuingCountry, nationality, gender, issueDate, expireDate, identityNumber, documentNumber, userid, cf1~cf3 등
주의사항:
- 문자열 데이터만 지원합니다. 이미지 데이터는 별도로 PUT Image API를 사용하세요.
- 보안 강화를 위해 요청 본문을 AES-256-ECB로 암호화하여 전송할 수 있습니다.
파트 3: 운영 배포
보안 강화
운영 환경 배포 전 아래 보안 설정을 완료하세요.1. API 키 안전하게 관리
1. API 키 안전하게 관리
API 키는 절대 클라이언트 코드(프론트엔드)나 git에 노출되어서는 안 됩니다.환경 변수 사용 (필수):백엔드 프록시 패턴 (권장):
.gitignore에 반드시 추가하세요:2. IP 화이트리스트 설정
2. IP 화이트리스트 설정
ARGOS API를 호출하는 서버 IP를 화이트리스트에 등록하면 허가되지 않은 IP에서의 API 접근이 차단됩니다(403).프로젝트 관리 → 프로젝트 설정 → 시스템 운영 → IP 화이트리스트 관리에서 서버 IP를 등록하세요:

3. 웹훅 데이터 암호화 활성화
3. 웹훅 데이터 암호화 활성화
웹훅으로 전송되는 민감한 KYC 데이터를 암호화할 수 있습니다.프로젝트 관리 → 보안설정 → 데이터 보호에서 **“안전한 데이터 전송”**을 ON으로 설정하세요.
활성화하면 웹훅 페이로드가 아래 형식으로 암호화되어 전달됩니다:복호화 방법 (AES-256-CBC):더 알아보기: 암호화 가이드

테스트 체크리스트
운영 배포 전 아래 항목들을 확인하세요.Liveform 플로우 테스트
기본 플로우
기본 플로우
- 기본 Liveform URL이 데스크톱/모바일에서 정상 로드됨
- QR 코드가 모바일에서 스캔되어 플로우 진행됨
- 카메라 권한 요청이 정상 동작함
- 문서 및 셀피 촬영 후 제출이 완료됨
쿼리 스트링 파라미터
쿼리 스트링 파라미터
-
email,userid파라미터로 사용자 정보가 미리 입력됨 - 암호화된 파라미터(
allowedCountries등)가 정상 동작함 - Token을 통한 Private mode URL이 정상 작동함
- 만료된 Token 접근 시 적절한 오류 화면이 표시됨
Return URL
Return URL
- 검증 완료 후 Return URL로 리디렉션됨
-
kycStatus,userid,email파라미터가 올바르게 전달됨 - 암호화 옵션 활성화 시
encrypted파라미터로 전달됨
웹훅 테스트
웹훅 수신 확인
웹훅 수신 확인
테스트 방법 1: webhook.site 사용테스트 방법 2: ngrok 사용 (로컬 개발)
- 웹훅 엔드포인트가 이벤트를 정상 수신함
-
approved,rejected,submit이벤트가 올바르게 처리됨 - 5초 이내에 200 OK 응답이 반환됨
- 중복 웹훅에 대한 멱등성 처리가 작동함
- 암호화된 웹훅이 올바르게 복호화됨
API 테스트
- GET Submission이 올바른 데이터를 반환함
-
userid,email로 조회가 가능함 - Token 등록(POST Token) 및 조회(GET Token)가 정상 동작함
- IP 화이트리스트가 활성화된 경우 허가된 IP에서만 접근 가능함
- 잘못된 API 키로 요청 시 403 응답이 반환됨
운영 전환 체크리스트
대시보드 설정 최종 확인
- 웹훅 URL이 운영 서버 주소로 설정됨 (HTTPS)
- IP 화이트리스트에 모든 운영 서버 IP가 등록됨
- Secure Data Transfer (웹훅 암호화)가 필요에 따라 설정됨
- Return URL이 운영 앱 주소로 설정됨
- 프로젝트 설정 (허용 문서 유형, 국가 블랙리스트, 연령 제한 등)이 요구사항과 일치함
코드 최종 확인
- API 키가 환경 변수에서 로드됨
- 코드에 하드코딩된 API 키가 없음
- 웹훅 핸들러에 오류 처리 및 로깅이 구현됨
- 웹훅 멱등성 처리가 구현됨
- 프론트엔드에서 ARGOS API를 직접 호출하지 않음


