메인 콘텐츠로 건너뛰기

완전한 ID check 온보딩 가이드

이 가이드는 처음으로 ID check를 서비스에 도입하는 고객사 개발자를 위해 작성되었습니다. 실제 통합 과정에서 맞닥뜨리는 고민들을 순서대로 짚어가며, 각 단계에서 ARGOS가 제공하는 기술을 안내합니다.
사전 준비물

ID check 통합의 핵심 원리

ID check를 시스템에 통합할 때, 가장 먼저 이해해야 할 내용이 있습니다.
ID check는 Liveform 기반의 서비스입니다.사용자가 신원을 인증하는 과정(카메라로 신분증 촬영, 셀피 촬영, AI 검증)은 ARGOS가 호스팅하는 Liveform에서 이루어집니다. 고객사가 이 UI를 직접 구축하거나 대체할 수 없습니다.고객사가 해야 할 일은 단 하나입니다: 사용자를 Liveform URL로 보내는 것.
API의 역할: ID check의 API는 ARGOS 시스템으로 들어오고 나가는 정보의 안전한 전송을 위한 파이프라인 역할을 합니다. 주요 용도는 다음과 같습니다.
목적관련 API설명
Token 관리POST/GET/DELETE TokenPrivate mode에서 일회용 URL 생성 및 관리
데이터 획득 및 관리GET/PATCH/DELETE Submission, GET Image검증 완료된 Submission 데이터 조회, 수정, 삭제, 이미지 조회
시스템 연결POST Review, PUT ImagePending 건 검수 처리, 이미지 추가/교체 등 워크플로우 연동
MigrationPOST Submission기존 KYC 데이터 이전, 특수한 상황에서 데이터 삽입, 개발 테스트

목차

파트 1: 기초

계정 설정, 핵심 개념 이해

파트 2: 통합

Liveform 연결, 결과 수신, 데이터 활용

파트 3: 운영

보안 강화, 테스트, 라이브 전환

파트 1: 기초

ARGOS ID check란?

ARGOS ID check는 AI 기반 신원 인증 플랫폼입니다. 사용자가 신분증을 촬영하고 셀피를 찍으면, AI가 문서 진위 여부를 분석하고 결과를 내려줍니다.

문서 검증

전 세계 200+ 국가의 여권, 운전면허증, 국가 신분증, 거주 허가증 등을 검증합니다.

AI 사기 탐지

위조, 사진 대체, 문서 변조를 AI로 자동 감지합니다.

데이터 추출

신분증에서 이름, 생년월일, 국적 등의 정보를 자동 추출합니다.

KYC/AML 컴플라이언스

검증 규칙 커스터마이즈 및 감사 추적(Audit Trail)을 제공합니다.

계정 설정 및 필수 정보 확인

1

계정 만들기

idcheck.argosidentity.com 에서 가입하고 이메일을 인증한 뒤 대시보드에 로그인하세요.
2

필수 정보 확인

대시보드에서 아래 세 가지 정보를 확인하세요. 각 항목은 신규 대시보드의 프로젝트 관리 메뉴에서 확인할 수 있습니다.1. Project ID (PID) 및 Liveform URL프로젝트 관리 → 프로젝트 설정 → 프로젝트 정보 에서 확인합니다.
  • Project ID (PID) — 프로젝트 고유 식별자
  • Liveform URL — 사용자에게 제공할 신원 인증 페이지 URL (프로젝트 파이프라인 섹션)
프로젝트 정보 — PID 및 Liveform URL 확인
2. API Key프로젝트 관리 → 프로젝트 설정 → 연동 정보 에서 확인합니다.
  • API Key — API 요청 인증에 사용 (절대 외부에 노출하지 마세요)
연동 정보 — API Key 확인
API Key:      argos_live_abc123xyz...
Project ID:   pid_abc123
Liveform URL: https://form.argosidentity.com?pid=pid_abc123
보안 주의: API 키는 비밀번호처럼 관리하세요. 클라이언트 코드(프론트엔드)에 노출하거나 git에 커밋해서는 안 됩니다. 항상 서버 측 환경 변수에 저장하세요.

핵심 개념

Submission은 단일 신원 인증 시도를 의미합니다. 사용자가 Liveform에서 신분증을 촬영하고 제출하면 Submission이 생성됩니다.주요 속성:
  • Submission ID — 고유 식별자 (예: sub_abc123)
  • KYC 상태approved (승인), rejected (거절), pending (수동 심사 대기)
  • 추출 데이터 — 이름, 생년월일, 국적 등
  • 이미지 — 신분증 사진과 셀피
  • 메타데이터 — 타임스탬프, IP, 고객사가 전달한 userid/email 등
Submission 상태 흐름:
(사용자가 Liveform 접속) → Created → Processing → Approved / Rejected / Pending
Liveform은 ARGOS가 호스팅하는 신원 인증 페이지입니다. 고객사는 이 URL을 사용자에게 제공하기만 하면 됩니다.
  • 데스크톱: QR 코드를 표시하여 모바일로 스캔 유도
  • 모바일: 바로 카메라 인터페이스로 진행
기본 URL 구조:
https://form.argosidentity.com?pid={project_id}
쿼리 스트링 파라미터를 추가하여 사용자 정보 전달, 국가 제한, 보안 옵션 등을 커스터마이즈할 수 있습니다.
웹훅은 검증 이벤트가 발생할 때 고객사 서버로 실시간 HTTP POST 요청을 보내는 기능입니다. 운영 환경에서 검증 결과를 받는 가장 권장되는 방법입니다.주요 이벤트:
  • approved — 검증 승인
  • rejected — 검증 거절
  • submit — 보류(pending) 상태로 제출
  • updated — 데이터 업데이트
  • deleted — Submission 삭제
  • created — Submission 생성
  • retry — 사용자 재시도
  • token_expired — Token 만료
  • injection — API를 통한 데이터 주입
  • aml — AML 검사 완료
  • aml_monitor — AML 온고잉 모니터링 결과
웹훅 URL은 프로젝트 관리 → 프로젝트 설정 → 연동 정보에서 등록합니다.
Token을 사용하면 Liveform URL을 일회용으로 만들 수 있습니다 (Private Mode).용도:
  • 동일한 URL이 여러 사람에게 공유되는 것 방지
  • 특정 사용자에게만 유효한 인증 링크 제공
  • 보안이 중요한 서비스(금융, 의료 등)에서 사용
작동 방식:
  • 서버에서 고유한 tokenId를 생성하여 ARGOS에 등록
  • token 파라미터를 Liveform URL에 추가하여 사용자에게 전달
  • 최초 사용 후 3분 또는 제출이 결정 상태에 도달하면 만료
Return URL은 사용자가 인증을 완료하고 “OK” 버튼을 누르거나 5초 후, 고객사 앱으로 돌아올 URL입니다.대시보드에서 설정하며, KYC 상태(kycStatus), 이메일, userid, 커스텀 필드 등이 쿼리 파라미터로 함께 전달됩니다.예시:
https://yourapp.com/verification-complete?kycStatus=approved&userid=user123&email=user@example.com
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 — 대시보드에서 별도로 발급받아 사용하는 전용 키 (발급 후 한 번만 표시되므로 분실 시 재발급 필요)
대시보드의 쿼리스트링 암복호화 툴(프로젝트 관리 → 프로젝트 설정 → 프로젝트 정보)로 코드 없이 직접 암호화된 URL을 생성하고 테스트할 수 있습니다.더 알아보기: 쿼리 스트링 및 토큰 가이드 | 암호화 가이드

파트 2: 통합

고객사 개발자가 실제로 직면하는 고민들을 단계별로 해결합니다.

Q1. “어떻게 내 앱에서 사용자에게 신원 인증을 시키나?”

답: Liveform URL을 사용자에게 전달하세요. 대시보드에서 Liveform URL을 복사하여 버튼 링크, 리디렉션, 이메일 링크 등 어떤 방식으로든 사용자에게 전달하면 됩니다.
1

Liveform URL 확인

대시보드 프로젝트 관리 → 프로젝트 설정 → 프로젝트 정보 의 프로젝트 파이프라인 섹션에서 Liveform URL을 복사하세요:
https://form.argosidentity.com?pid={your_project_id}
2

앱에서 사용자에게 전달

웹앱 — 링크 버튼:
<a href="https://form.argosidentity.com?pid={your_pid}" target="_blank">
  신원 인증하기
</a>
모바일 앱 — 외부 브라우저 열기:
// React Native 예시
import { Linking } from 'react-native';

const startVerification = () => {
  Linking.openURL('https://form.argosidentity.com?pid={your_pid}');
};
백엔드에서 리디렉션:
// Node.js Express 예시
app.get('/verify', (req, res) => {
  res.redirect('https://form.argosidentity.com?pid={your_pid}');
});
3

기본 플로우 확인

브라우저에서 URL을 직접 열어 기본 검증 플로우를 테스트하세요.
Liveform Interface from pc
Liveform Interface from mobile
  • 데스크톱: QR 코드가 표시되며, 모바일로 스캔하여 계속 진행
  • 모바일: 바로 카메라 인터페이스로 진행

Q2. “내 서비스의 사용자 정보를 미리 전달할 수 있나?”

답: 쿼리 스트링 파라미터를 URL에 추가하세요. 사용자가 이미 회원 가입을 한 상태라면, 이메일·사용자 ID 등을 미리 넣어주면 사용자가 Liveform에서 다시 입력하지 않아도 됩니다. 또한 이 값들은 Submission 데이터와 함께 저장되어 나중에 웹훅이나 GET Submission API로 조회할 때 활용할 수 있습니다. 주요 파라미터:
파라미터설명예시
email사용자 이메일user@example.com
userid내부 사용자 IDuser_12345
cf1, cf2, cf3커스텀 메타데이터 (예: 캠페인 ID, 서비스 구분)campaign_summer
sidSubmission ID (업데이트 시 사용)sub_abc123
예시 URL:
const email = encodeURIComponent("user@example.com");
const userid = "user_12345";
const liveformUrl = `https://form.argosidentity.com?pid={your_pid}&email=${email}&userid=${userid}&cf1=campaign_summer`;
userid에 내부 시스템의 사용자 ID를 넣어두면, 나중에 웹훅이나 GET Submission API에서 이 값으로 해당 사용자의 인증 결과를 바로 찾을 수 있습니다.

Q3. “URL이 여러 사람에게 공유되는 게 우려된다”

답: Token을 등록하여 Private Mode (일회용 URL)를 사용하세요. Token을 Liveform URL에 추가하면, 해당 URL은 일회용이 됩니다. 최초 사용 후 3분이 지나거나 인증이 완료되면 더 이상 사용할 수 없습니다.
1

서버에서 고유 tokenId 생성 후 ARGOS에 등록

curl -X POST 'https://rest-api.argosidentity.com/v3/submission/tokens' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: text/plain' \
  -d '{"tokenId": ["user-session-001", "user-session-002"]}'
응답:
{
  "success": true,
  "message": "All tokens are now in the pool",
  "summary": {
    "totalSubmitted": 2,
    "currentCount": 2
  }
}
Token 등록 API는 반드시 서버 측에서만 호출하세요. API 키가 포함되므로 클라이언트(프론트엔드)에서 직접 호출해서는 안 됩니다.
2

Token이 포함된 Liveform URL을 사용자에게 전달

const tokenId = "user-session-001";
const secureUrl = `https://form.argosidentity.com?pid={your_pid}&token=${tokenId}`;

// 이메일, SMS 등을 통해 사용자에게 전달
sendEmail(userEmail, `인증 링크: ${secureUrl}`);
3

Token 만료 처리

Token은 다음 경우에 무효화됩니다:
  • 최초 사용 후 3분 경과
  • 해당 Token으로 Submission이 결정 상태(승인/거절/보류)에 도달
Token이 만료되면 사용자에게 새로운 Token을 생성하여 전달하세요.Token 관련 제한사항:
  • 프로젝트당 최대 100,000개 Token 보관 가능
  • API 요청당 최대 500개 Token 등록 가능
  • Token ID 형식: 8–64자, 영숫자 + -_.
더 알아보기: POST Token API | 쿼리 스트링 및 토큰 가이드

Q4. “특정 국가 또는 문서 유형만 허용하고 싶다”

답: 암호화된 쿼리 스트링 파라미터를 사용하세요. allowedCountries, allowedIdTypes 등 보안이 필요한 파라미터는 암호화하여 encrypted 파라미터에 담아야 합니다. 암호화 모듈은 AES-256-ECB 또는 AES-256-GCM 중 선택할 수 있으며, 암호화 키는 프로젝트 API 키 또는 대시보드에서 별도 발급한 Custom secretKey를 사용할 수 있습니다.
대시보드에서 바로 암호화된 URL 만들기코드 없이 암호화된 Liveform URL을 생성하고 테스트하려면 대시보드의 쿼리스트링 암복호화 툴을 활용하세요.프로젝트 관리 → 프로젝트 설정 → 프로젝트 정보 → 쿼리스트링 암복호화 툴암호화할 파라미터를 입력하면 암호화된 URL이 자동 생성되며, 기존 암호화된 URL을 복호화하여 포함된 파라미터를 확인할 수도 있습니다.
쿼리스트링 암복호화 툴 화면
코드로 암호화하는 방법:
const CryptoJS = require('crypto-js');

function encryptQueryParams(data, apiKey) {
  const hashedKey = CryptoJS.SHA256(apiKey);
  const key = CryptoJS.lib.WordArray.create(hashedKey.words.slice(0, 8), 32);
  const encrypted = CryptoJS.AES.encrypt(
    JSON.stringify(data),
    key,
    { mode: CryptoJS.mode.ECB }
  );
  return encrypted.ciphertext.toString(CryptoJS.enc.Base64);
}

// 예시 1: 허용 국가 및 문서 유형 제한
const config1 = {
  allowedCountries: "USA,KOR,JPN",        // ISO Alpha-3 코드
  allowedIdTypes: "passport,drivers_license"
};

// 예시 2: 국가 및 문서 유형 미리 선택 (선택 화면 건너뛰기)
const config2 = {
  selectedIssuingCountry: "KOR",
  selectedIdType: "drivers_license"
};

const encrypted = encryptQueryParams(config1, YOUR_API_KEY);
const liveformUrl = `https://form.argosidentity.com?pid={your_pid}&encrypted=${encodeURIComponent(encrypted)}`;
암호화가 필요한 파라미터:
파라미터설명
allowedCountries허용할 국가 (ISO Alpha-3 코드, 쉼표 구분)
allowedIdTypes허용할 문서 유형
selectedIssuingCountry국가 선택 화면을 건너뛰고 지정
selectedIdType문서 유형 선택 화면을 건너뛰고 지정 (반드시 selectedIssuingCountry와 함께 사용)
projectionId / projectionName특정 필드를 제외하는 Projection 적용
auxidField추가 신원 검증 (예: 전화번호 SMS 인증)
selectedIdType은 반드시 selectedIssuingCountry와 함께 사용해야 합니다. 단독 사용 시 오류가 발생합니다.
더 알아보기: 쿼리 스트링 및 토큰 가이드

Q5. “인증 완료 후 사용자를 내 앱으로 돌려보내고 싶다”

답: 대시보드에서 Return URL을 설정하세요. 사용자가 인증을 마치고 “OK”를 누르면 설정한 URL로 리디렉션됩니다. KYC 결과가 쿼리 파라미터로 함께 전달됩니다.
1

대시보드에서 Return URL 설정

프로젝트 관리 → 프로젝트 설정 → 연동 정보에서 Return URL을 입력하세요:
리턴 URL 설정 화면
https://yourapp.com/verification-complete
2

리디렉션 결과 처리

사용자는 아래와 같은 파라미터와 함께 리디렉션됩니다:
https://yourapp.com/verification-complete?kycStatus=approved&userid=user123&email=user@example.com&cf1=campaign_summer
전달되는 파라미터:
  • kycStatusapproved, rejected, pending
  • userid — Liveform URL에 전달했던 사용자 ID
  • email — 사용자 이메일
  • cf1, cf2, cf3 — 커스텀 필드
// Express.js 예시
app.get('/verification-complete', async (req, res) => {
  const { userid, kycStatus } = req.query;

  if (kycStatus === 'approved') {
    await updateUser(userid, { verified: true });
    res.render('verification-success');
  } else if (kycStatus === 'pending') {
    res.render('verification-pending');
  } else {
    res.render('verification-rejected');
  }
});
Return URL로 전달되는 kycStatus는 사용자 경험(UX) 화면 전환용입니다. 검증 결과를 데이터베이스에 기록하거나 내부 시스템에 반영하는 공식 채널로는 웹훅을 사용하는 것을 권장합니다. Return URL 파라미터는 변조될 수 있습니다.
더 알아보기: Return URL 가이드

Q6. “인증 결과를 실시간으로 서버에서 받고 싶다”

답: 웹훅(Webhook)을 설정하세요. 웹훅은 인증 이벤트가 발생할 때 고객사 서버로 즉시 HTTP POST 요청을 보내는 기능입니다. 이 방법이 인증 결과를 수신하는 가장 안정적이고 권장되는 방법입니다.
1

웹훅 엔드포인트 생성

POST 요청을 받을 HTTPS 엔드포인트를 서버에 만드세요:
// Node.js Express 예시
const express = require('express');
const app = express();
app.use(express.json());

app.post('/webhooks/idcheck', async (req, res) => {
  const event = req.body;

  // 이벤트 유형에 따라 처리
  switch (event.webhook_trigger) {
    case 'approved':
      // 사용자 검증 완료 처리
      await db.users.update({ id: event.userid, verified: true });
      break;

    case 'rejected':
      // 검증 거절 처리
      await db.users.update({ id: event.userid, verified: false });
      break;

    case 'submit':
      // 수동 심사 대기 처리
      await notifyAdmin(`${event.userid} 수동 심사 필요`);
      break;
  }

  // 반드시 빠르게 200 응답 (5초 이내)
  res.status(200).json({ received: true });
});
중요한 웹훅 구현 원칙:
  • 항상 5초 이내에 200 OK 응답을 반환하세요. 응답이 없으면 ARGOS가 재전송합니다.
  • 처리 로직은 200 응답 이후 비동기로 실행하세요.
  • 동일한 Submission ID로 중복 웹훅이 올 수 있으므로 멱등성(idempotency) 처리를 구현하세요.
2

대시보드에서 웹훅 URL 등록

프로젝트 관리 → 프로젝트 설정 → 연동 정보웹훅 설정 섹션에서 엔드포인트 URL을 입력하세요:
https://yourapp.com/webhooks/idcheck
웹훅 설정 화면
웹훅 URL은 반드시 HTTPS를 사용해야 합니다. 로컬 개발 시에는 ngrok 또는 webhook.site를 사용하여 테스트하세요.
3

웹훅 이벤트 확인

전체 이벤트 유형:
이벤트설명활용 예시
approved검증 승인사용자 상태 업데이트, 서비스 이용 허가
rejected검증 거절사용자 알림, 재제출 요청
submit보류(pending) 상태관리자 알림, 수동 심사 요청
updated데이터 업데이트DB 동기화
deletedSubmission 삭제관련 데이터 정리
createdSubmission 생성인증 시작 추적
retry사용자 재시도재시도 패턴 모니터링
token_expiredToken 만료새 Token 발급
injectionAPI를 통한 데이터 주입(Injection)API 작업 로깅
amlAML 검사 완료컴플라이언스 결과 처리
aml_monitorAML 온고잉 모니터링 결과지속적 모니터링 처리
더 알아보기: 웹훅 이벤트 상세 가이드

Q7. “인증 데이터를 우리 DB/시스템과 연동하고 싶다”

답: GET Submission API로 검증 데이터를 조회하세요. 웹훅으로 실시간 수신도 가능하지만, 필요한 시점에 직접 특정 Submission의 데이터를 조회하고 싶을 때 GET Submission API를 사용합니다.
# Submission ID로 단일 조회
curl -X GET 'https://rest-api.argosidentity.com/v3/submission?submission_id={submission_id}' \
  -H 'x-api-key: YOUR_API_KEY'

# 사용자 ID로 조회
curl -X GET 'https://rest-api.argosidentity.com/v3/submission?userid={userid}' \
  -H 'x-api-key: YOUR_API_KEY'

# 이메일로 조회
curl -X GET 'https://rest-api.argosidentity.com/v3/submission?email={email}' \
  -H 'x-api-key: YOUR_API_KEY'

# 전체 목록 조회 (페이지네이션)
curl -X GET 'https://rest-api.argosidentity.com/v3/submission?count=50' \
  -H 'x-api-key: YOUR_API_KEY'
조회 파라미터:
파라미터설명
submission_id특정 제출 건의 고유 ID로 단일 조회
userid사용자 ID와 일치하는 모든 제출 건 조회
email이메일과 일치하는 모든 제출 건 조회
count반환할 결과 수 (기본값: 50)
start_date / end_date조회 기간 필터 (YYYY-MM-DD)
request_type특정 데이터 유형만 조회 (kyc, aml, data, others)
응답 예시:
{
  "Items": [
    {
      "data": {
        "full_name": "John Doe",
        "gender": "male",
        "nationality": "USA",
        "date_of_birth": "1990-01-01",
        "idType": "passport",
        "idcard_issuingCountry": "USA",
        "cf1": "campaign_summer"
      },
      "email": "user@example.com",
      "submission_id": "sub_abc123",
      "userid": "user_12345",
      "created_at": "2024-01-15-10-30-00-000",
      "kyc": {
        "result": "approved",
        "comment": [],
        "commentCode": []
      },
      "image": {
        "idImage": "{idImage URL}",
        "selfieImage": "{selfieImage URL}"
      }
    }
  ]
}
기타 데이터 관리 및 시스템 연결 API:
API용도
PATCH /submissionSubmission 데이터 수정 (kycStatus, fullName, email 등)
DELETE /submissionSubmission 전체 삭제 (GDPR 등 개인정보 삭제 요청 대응)
DELETE /submission/partial이미지만 삭제 (메타데이터 유지)
GET /imageSubmission에 저장된 이미지(신분증, 셀피 등) 조회
PUT /image기존 Submission에 이미지 추가 또는 교체 (Base64 인코딩)
POST /submission/reviewPending 상태의 Submission을 API로 승인/거절 처리 (수동 심사 자동화)
POST /submission/review 는 프로젝트 설정에서 검토자가 ‘Client’로 설정된 경우, 고객사가 API를 통해 직접 pending 건을 심사할 수 있게 해줍니다. 이미 승인/거절된 건은 수정할 수 없습니다.
더 알아보기: GET Submission API | REVIEW API

Q8. “기존에 보유한 KYC 데이터를 ARGOS에 이전하고 싶다”

답: POST Submission API (Migration)를 사용하세요. 이 API는 다음과 같은 상황에서 사용합니다:
  • 데이터 마이그레이션: 기존 시스템의 KYC 완료 데이터를 ARGOS 대시보드로 이전
  • 특수한 상황: ID Check 검증을 거치기 어려운 예외적 케이스에서 직접 데이터 삽입
  • 개발 및 테스트: 개발 단계에서 다양한 시나리오를 테스트할 때 활용
이 API를 통해 생성된 Submission은 ARGOS의 표준 검증 절차(AI 검증)를 거치지 않습니다. 제출된 데이터의 정확성과 유효성에 대한 책임은 전적으로 고객사에게 있습니다.일반적인 신규 사용자의 신원 인증은 반드시 Liveform을 통해 진행해야 합니다.
curl -X POST 'https://rest-api.argosidentity.com/v3/submission/migration' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{
    "admin": "admin@yourcompany.com",
    "email": "user@example.com",
    "fullName": "John Doe",
    "birthDate": "1990-01-01",
    "kycStatus": "approved",
    "idType": "passport",
    "issuingCountry": "USA",
    "nationality": "USA",
    "gender": "male",
    "userid": "user_12345"
  }'
필수 필드:
필드설명
admin프로젝트 관리자 이메일 (대시보드에 등록되어 있어야 함)
emailKYC 제출자의 이메일 주소
fullName제출자의 전체 이름
birthDate생년월일 (YYYY-MM-DD)
kycStatusapproved 또는 rejected
선택 필드: idType, issuingCountry, nationality, gender, issueDate, expireDate, identityNumber, documentNumber, userid, cf1~cf3 주의사항:
  • 문자열 데이터만 지원합니다. 이미지 데이터는 별도로 PUT Image API를 사용하세요.
  • 보안 강화를 위해 요청 본문을 AES-256-ECB로 암호화하여 전송할 수 있습니다.
더 알아보기: POST Submission API

파트 3: 운영 배포

보안 강화

운영 환경 배포 전 아래 보안 설정을 완료하세요.
API 키는 절대 클라이언트 코드(프론트엔드)나 git에 노출되어서는 안 됩니다.환경 변수 사용 (필수):
# .env 파일
ARGOS_API_KEY=argos_live_abc123xyz...
ARGOS_PROJECT_ID=pid_abc123
// Node.js에서 로드
require('dotenv').config();
const apiKey = process.env.ARGOS_API_KEY;
백엔드 프록시 패턴 (권장):
// ❌ 프론트엔드에서 직접 ARGOS API 호출 — 절대 금지
// fetch('https://rest-api.argosidentity.com/...', { headers: { 'x-api-key': '...' } })

// ✅ 프론트엔드는 자체 백엔드 API만 호출
// 백엔드 서버에서 ARGOS API 호출 후 결과 전달
app.post('/api/start-verification', authenticateUser, async (req, res) => {
  const tokenId = `session-${req.user.id}-${Date.now()}`;

  // 서버 측에서만 ARGOS API 호출
  await fetch('https://rest-api.argosidentity.com/v3/submission/tokens', {
    method: 'POST',
    headers: { 'x-api-key': process.env.ARGOS_API_KEY, 'Content-Type': 'text/plain' },
    body: JSON.stringify({ tokenId: [tokenId] })
  });

  const liveformUrl = `https://form.argosidentity.com?pid=${process.env.ARGOS_PROJECT_ID}&token=${tokenId}`;
  res.json({ liveformUrl });
});
.gitignore에 반드시 추가하세요:
.env
.env.local
.env.production
ARGOS API를 호출하는 서버 IP를 화이트리스트에 등록하면 허가되지 않은 IP에서의 API 접근이 차단됩니다(403).프로젝트 관리 → 프로젝트 설정 → 시스템 운영 → IP 화이트리스트 관리에서 서버 IP를 등록하세요:
IP 화이트리스트 관리 화면
52.12.34.56
52.12.34.57
API를 호출하는 모든 서버 IP를 등록해야 합니다: 운영 서버, 스테이징 서버, CI/CD 파이프라인 IP 등.
웹훅으로 전송되는 민감한 KYC 데이터를 암호화할 수 있습니다.프로젝트 관리 → 보안설정 → 데이터 보호에서 **“안전한 데이터 전송”**을 ON으로 설정하세요.
보안 데이터 전송 설정
활성화하면 웹훅 페이로드가 아래 형식으로 암호화되어 전달됩니다:
{
  "response": {
    "body": "encrypted-string"
  }
}
복호화 방법 (AES-256-CBC):
const CryptoJS = require('crypto-js');

function decryptWebhook(encryptedData, apiKey) {
  const hashedKey = CryptoJS.SHA256(apiKey);
  const key = CryptoJS.lib.WordArray.create(hashedKey.words.slice(0, 8), 32);
  const iv = CryptoJS.lib.WordArray.create(hashedKey.words.slice(8, 12), 16);

  const cipherParams = CryptoJS.lib.CipherParams.create({
    ciphertext: CryptoJS.enc.Base64.parse(encryptedData)
  });

  const decrypted = CryptoJS.AES.decrypt(cipherParams, key, {
    iv: iv,
    mode: CryptoJS.mode.CBC,
    padding: CryptoJS.pad.Pkcs7
  });

  return JSON.parse(decrypted.toString(CryptoJS.enc.Utf8));
}

app.post('/webhooks/idcheck', (req, res) => {
  const event = decryptWebhook(req.body.response.body, process.env.ARGOS_API_KEY);
  // 이벤트 처리...
  res.status(200).json({ received: true });
});
암호화 방식 차이:
  • 웹훅 복호화: AES-256-CBC
  • API 요청/응답: AES-256-ECB
  • 쿼리 스트링: AES-256-ECB 또는 AES-256-GCM
각 용도별 암호화 방식을 혼동하지 마세요.
더 알아보기: 암호화 가이드

테스트 체크리스트

운영 배포 전 아래 항목들을 확인하세요.
1

Liveform 플로우 테스트

  • 기본 Liveform URL이 데스크톱/모바일에서 정상 로드됨
  • QR 코드가 모바일에서 스캔되어 플로우 진행됨
  • 카메라 권한 요청이 정상 동작함
  • 문서 및 셀피 촬영 후 제출이 완료됨
  • email, userid 파라미터로 사용자 정보가 미리 입력됨
  • 암호화된 파라미터(allowedCountries 등)가 정상 동작함
  • Token을 통한 Private mode URL이 정상 작동함
  • 만료된 Token 접근 시 적절한 오류 화면이 표시됨
  • 검증 완료 후 Return URL로 리디렉션됨
  • kycStatus, userid, email 파라미터가 올바르게 전달됨
  • 암호화 옵션 활성화 시 encrypted 파라미터로 전달됨
2

웹훅 테스트

테스트 방법 1: webhook.site 사용
1. https://webhook.site 방문
2. 생성된 고유 URL 복사
3. 대시보드 Webhook URL 필드에 입력
4. Liveform에서 테스트 인증 수행
5. webhook.site에서 페이로드 확인
테스트 방법 2: ngrok 사용 (로컬 개발)
# 로컬 서버 실행
node server.js   # 포트 3000

# 별도 터미널에서 외부 노출
ngrok http 3000

# 생성된 HTTPS URL을 대시보드에 입력
# 예: https://abc123.ngrok.io/webhooks/idcheck
  • 웹훅 엔드포인트가 이벤트를 정상 수신함
  • approved, rejected, submit 이벤트가 올바르게 처리됨
  • 5초 이내에 200 OK 응답이 반환됨
  • 중복 웹훅에 대한 멱등성 처리가 작동함
  • 암호화된 웹훅이 올바르게 복호화됨
3

API 테스트

  • GET Submission이 올바른 데이터를 반환함
  • userid, email로 조회가 가능함
  • Token 등록(POST Token) 및 조회(GET Token)가 정상 동작함
  • IP 화이트리스트가 활성화된 경우 허가된 IP에서만 접근 가능함
  • 잘못된 API 키로 요청 시 403 응답이 반환됨
4

보안 테스트

  • API 키가 클라이언트 코드에 노출되지 않음
  • API 키가 git 이력에 포함되지 않음
  • 웹훅 URL이 HTTPS를 사용함
  • Return URL 파라미터만으로 권한을 부여하지 않음 (웹훅을 통해 검증)

운영 전환 체크리스트

1

대시보드 설정 최종 확인

  • 웹훅 URL이 운영 서버 주소로 설정됨 (HTTPS)
  • IP 화이트리스트에 모든 운영 서버 IP가 등록됨
  • Secure Data Transfer (웹훅 암호화)가 필요에 따라 설정됨
  • Return URL이 운영 앱 주소로 설정됨
  • 프로젝트 설정 (허용 문서 유형, 국가 블랙리스트, 연령 제한 등)이 요구사항과 일치함
2

코드 최종 확인

  • API 키가 환경 변수에서 로드됨
  • 코드에 하드코딩된 API 키가 없음
  • 웹훅 핸들러에 오류 처리 및 로깅이 구현됨
  • 웹훅 멱등성 처리가 구현됨
  • 프론트엔드에서 ARGOS API를 직접 호출하지 않음
3

모니터링 설정

운영 중 추적할 주요 지표:
  • 검증 시작 수 vs 완료 수
  • 승인 / 거절 / 보류 비율
  • 웹훅 수신 실패율
  • Token 만료로 인한 재발급 빈도

다음 단계

통합을 완료했다면 아래 문서들을 참고하여 고급 기능을 탐색하세요.