POST/Face-auth - ARGOS Identity

엔드포인트가 /v3/face-auth로 변경되었습니다.응답이 { score, authentication_id, ... }에서 FaceAuthSubmission 객체로 바뀌었고, 성공 상태 코드도 200에서 201 Created 가 되었습니다. 기존 연동을 옮기려면 FaceAuth 공통 참조 — 구 API에서 옮기기를 확인하세요.

먼저 확인하세요 — FaceAuth는 2가지 방식이 있습니다.이 API는 고객사가 카메라 UI를 직접 구현하고 촬영 이미지를 전송하는 방식입니다. 이 방식은 Active Liveness를 지원하지 않으므로, 휴대폰 화면 재생·정지 사진 등 스푸핑 시도를 차단할 수 없습니다. 실제 촬영(라이브니스) 검증이 필요하다면 Face Auth URL 방식을 권장합니다.→ 두 방식 비교 및 URL 방식 가이드: FaceAuth 시작하기 · FACE AUTH 가이드

승인된 KYC submission의 reference image와 전달한 얼굴 이미지를 비교해 FaceAuth submission을 생성합니다. 생성 결과가 rejected여도 요청 자체는 정상 처리되었으므로 201 Created를 반환합니다.

Notes

인증 결과는 옵션 설정과 임계치 값에 따라 결정되며, 승인(approved) 또는 거절(rejected) 상태로 반환됩니다.
faceImage 권장 사양: 960 x 720
submissionId 확인 방법: 대시보드에 로그인한 후 설정 > 라이브폼 URL을 클릭하여 ID Check 절차를 진행합니다. ID Check가 승인된 후에는 대시보드의 사용자 관리 메뉴 > 제출 목록에서 submissionId 데이터를 확인할 수 있습니다. 단, ID Check의 최종 상태가 반드시 승인이어야 합니다.
API Key 관련 안내: 기존 라이브폼 API Key와는 다른 별도의 API Key가 필요합니다. 애드온 시작하기 — 애드온 API 키 확인하기에서 확인할 수 있습니다.

1. Base URL

POST/Face-auth

POST https://rest-api.argosidentity.com/v3/face-auth

2. 인증

x-api-key header에 FaceAuth 프로젝트 API key를 포함해야 합니다.

x-api-key

x-api-key: {yourAPIKey}

3. 요청 예시

multipart/form-data를 사용합니다.

HTTP client library가 multipart boundary를 자동으로 설정하도록 해야 하며, Content-Type header를 직접 고정하지 마세요.

POST/Face-auth

curl -X POST "https://rest-api.argosidentity.com/v3/face-auth" \
  -H "x-api-key: {yourAPIKey}" \
  -F "submissionId={approvedKycSubmissionId}" \
  -F "faceImage=@./face.jpg" \
  -F "userId={yourUserId}"

4. 요청 본문

string

필수

비교 기준이 되는 승인된 KYC submission의 ID입니다. 동일 FaceAuth 프로젝트에 속해야 합니다.

file

필수

비교 대상 얼굴 이미지 파일입니다. 내용이 비어 있지 않은 이미지 파일이어야 합니다. PPE(머리 보호구, 얼굴 보호구) 옵션을 사용할 경우 정확한 인식을 위해 이미지에 모든 안전장비가 명확하게 포함되어야 합니다.base64 문자열은 지원하지 않습니다. 파일로 전송하세요.

string

고객사 사용자 식별자입니다.

string

고객사 custom field 1의 값입니다.

string

고객사 custom field 2의 값입니다.

string

고객사 custom field 3의 값입니다.

정의되지 않은 field, 같은 field의 중복 전달, faceImage 또는 submissionId 누락은 허용하지 않습니다.
userId, cf1, cf2, cf3는 제출 시 함께 저장되지만 조회 응답에는 포함되지 않습니다. 대시보드 또는 FaceAuth 웹훅에서 확인하세요.

5. 응답

5-1. 성공

제출 생성에 성공하면 201 Created와 함께 FaceAuthSubmission 객체가 돌아옵니다. authId는 이후 단건 조회·이미지 다운로드·삭제 요청의 path parameter로 사용합니다.

result.json

{
  "authId": "sampleAuthId1",
  "authStatus": "approved",
  "createTime": "2026-08-12T03:00:00.000Z",
  "submitType": "api",
  "kycSubmissionId": "sampleKycSubmissionId1",
  "deleteTime": null,
  "result": {
    "faceSimilarity": 99.5,
    "livenessScore": null,
    "activeLivenessScore": null,
    "occluded": null,
    "faceCover": null,
    "headCover": null
  },
  "signals": null,
  "rejectComment": null,
  "failCode": null
}

이 endpoint의 응답에는 policy가 포함되지 않습니다. 나머지 field는 공통 참조와 같습니다.판정에 사용한 정책이 필요하면 생성 응답의 authId로 단건 조회를 호출하세요. 조회 응답의 policy는 생성 시점 snapshot이므로, 이후 프로젝트 설정을 변경해도 그 제출을 판정한 기준을 그대로 확인할 수 있습니다.

이 endpoint에서 돌아오는 객체는 다음 값이 고정됩니다.

submitType은 항상 api입니다.
deleteTime은 항상 null입니다.
signals는 항상 null입니다. Face Auth URL 화면에서만 수집되는 값입니다.
result.activeLivenessScore는 항상 null입니다. API 방식에서는 Active Liveness를 실행하지 않습니다.

POST 응답과 이후 같은 authId의 단건 조회 응답은 같은 객체입니다. Active Liveness가 필요하면 Face Auth URL 흐름을 사용해야 합니다.

5-2. 거절

판정에 실패한 경우에도 HTTP error가 아니라 201 Created와 authStatus: "rejected"를 반환합니다. 성공/거절은 authStatus 값으로 판별하세요. HTTP 4xx/5xx는 요청 자체가 처리되지 않은 경우입니다.

result.json

{
  "authId": "sampleAuthId2",
  "authStatus": "rejected",
  "createTime": "2026-08-12T03:00:00.000Z",
  "submitType": "api",
  "kycSubmissionId": "sampleKycSubmissionId1",
  "deleteTime": null,
  "result": {
    "faceSimilarity": 72.4,
    "livenessScore": null,
    "activeLivenessScore": null,
    "occluded": null,
    "faceCover": null,
    "headCover": null
  },
  "signals": null,
  "rejectComment": [
    "face compare similarity score is lower than threshold"
  ],
  "failCode": [
    "face_compare_underscore"
  ]
}

5-3. 거절 코드(failCode)

failCode 값에 대소문자가 섞여 있으므로 문자열을 그대로 비교해야 합니다. 정규화하지 마세요.

failCode	거절 사유	대응 정책
`face_compare_underscore`	얼굴 유사도가 threshold 미만입니다.	`faceSimilarity`
`Face_Occluded_fail`	얼굴이 가려진 것으로 감지됐습니다.	`occluded`
`Face_cover_fail`	얼굴 보호장비 착용이 확인되지 않았습니다. 보호장비가 감지되지 않았거나 감지 신뢰도가 threshold 미만입니다.	`faceCover`
`Head_cover_fail`	머리 보호장비 착용이 확인되지 않았습니다. 보호장비가 감지되지 않았거나 감지 신뢰도가 threshold 미만입니다.	`headCover`
`liveness_fail`	Passive Liveness 점수가 threshold 미만입니다.	`liveness`
`active_liveness_fail`	Active Liveness 점수가 threshold 미만입니다. API 방식에서는 발생하지 않습니다.	`activeLiveness`

Face_Occluded_fail과 Face_cover_fail은 이름이 비슷하지만 원인이 반대입니다. 전자는 얼굴을 가려서 거절된 것이고, 후자는 보호장비를 착용하지 않아서 거절된 것입니다. 두 정책을 동시에 켜면 서로 충돌할 수 있으므로 용도에 맞는 하나만 사용하세요.맨얼굴로 제출했는데 Face_cover_fail이나 Head_cover_fail이 나오는 것은 정상 동작입니다. 보호장비 착용을 요구하는 정책이 켜져 있다는 뜻이므로, 해당 정책이 필요 없으면 프로젝트 설정에서 끄세요.

거절 사유 배열의 대응 관계와 파싱 방법은 FaceAuth 공통 참조 — rejectComment와 failCode를 참고하세요.

6. 오류 응답

아르고스 애플리케이션이 반환하는 오류는 { code, message } 형식입니다. 인증 계층에서 차단된 401과 일부 403은 이 형식을 따르지 않습니다. FaceAuth 공통 참조 — 인증 계층 오류를 참고하세요.

HTTP status	code	발생 조건
`400`	`REQUEST_INVALID`	multipart 형식, boundary, required field, 중복·미정의 field가 올바르지 않은 경우. `faceImage`가 비어 있거나 이미지로 처리할 수 없는 파일인 경우도 포함합니다
`400`	`FACEAUTH_FACE_NOT_DETECTED`	얼굴 이미지에서 비교 가능한 얼굴을 찾지 못한 경우
`403`	`AUTH_FORBIDDEN`	API key는 유효하지만 FaceAuth 프로젝트에 연결되지 않은 경우
`404`	`SUBMISSION_NOT_FOUND`	KYC submission이 없거나 삭제됐거나 다른 프로젝트에 속한 경우
`409`	`SUBMISSION_NOT_APPROVED`	KYC submission이 승인되지 않았거나 reference image가 없는 경우
`503`	`UPSTREAM_UNAVAILABLE`	얼굴 분석에 필요한 내부 서비스를 일시적으로 사용할 수 없는 경우. 잠시 후 동일 요청을 재시도합니다
`500`	`INTERNAL_UNEXPECTED`	예상하지 못한 서버 오류

위 표는 POST /v3/face-auth API 방식에서 반환되는 코드입니다. Face Auth URL 방식의 에러 코드(PV-40015, SE-50010~SE-50014 등)와 사용자에게 노출되는 문구는 Face Auth URL 검증 및 에러 처리를 참고하세요.

​1. Base URL

​2. 인증

​3. 요청 예시

​4. 요청 본문

​5. 응답

​5-1. 성공

​5-2. 거절

​5-3. 거절 코드(failCode)

​6. 오류 응답

1. Base URL

2. 인증

3. 요청 예시

4. 요청 본문

5. 응답

5-1. 성공

5-2. 거절

5-3. 거절 코드(failCode)

6. 오류 응답