GET/Face-auth/{authId}

단건 조회는 목록 조회와 별도 endpoint입니다.구 엔드포인트에서 GET /v3/faceauth?authId=...로 조회하던 방식이 GET /v3/face-auth/{authId} path parameter 방식으로 바뀌었습니다. 기존 연동을 옮기려면 FaceAuth 공통 참조 — 구 API에서 옮기기를 확인하세요.

FaceAuth 제출 건 하나를 조회합니다. 생성 직후에도 색인 반영을 기다릴 필요 없이 authId로 바로 조회할 수 있습니다.

1. Base URL

GET https://rest-api.argosidentity.com/v3/face-auth/{authId}

GET https://kr.rest-api.argosidentity.com/v3/face-auth/{authId}

2. 인증

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

x-api-key

x-api-key: {yourAPIKey}

3. 요청 예시

curl -X GET "https://rest-api.argosidentity.com/v3/face-auth/{authId}" \
  -H "x-api-key: {yourAPIKey}"

curl -X GET "https://kr.rest-api.argosidentity.com/v3/face-auth/{authId}" \
  -H "x-api-key: {yourAPIKey}"

4. Path 파라미터

string

필수

FaceAuth submission의 키값입니다. POST 생성 응답 또는 목록 응답의 authId를 사용합니다.

5. 응답

result.json

{
  "authId": "sampleAuthId1",
  "authStatus": "approved",
  "createTime": "2026-08-11T10:09:14.028Z",
  "submitType": "form",
  "kycSubmissionId": "sampleKycSubmissionId1",
  "deleteTime": null,
  "policy": {
    "faceSimilarity": { "enabled": true, "threshold": 85 },
    "occluded": { "enabled": false, "threshold": null },
    "faceCover": { "enabled": false, "threshold": null },
    "headCover": { "enabled": false, "threshold": null },
    "liveness": { "enabled": false, "threshold": null },
    "activeLiveness": { "enabled": true, "threshold": 75 }
  },
  "result": {
    "faceSimilarity": 100,
    "livenessScore": null,
    "activeLivenessScore": 90.60411071777344,
    "occluded": null,
    "faceCover": null,
    "headCover": null
  },
  "signals": {
    "startButtonClickTime": "2026-08-11T10:08:54.742Z",
    "cameraProcessInfo": [
      {
        "processStartTime": "2026-08-11T10:08:57.300Z",
        "processEndTime": "2026-08-11T10:09:12.278Z",
        "type": "faceAuth-passive",
        "error": null
      }
    ]
  },
  "rejectComment": null,
  "failCode": null
}

5-1. 성공

단건 조회에 성공하면 200 OK와 함께 FaceAuthSubmission 객체가 돌아옵니다. 객체 하나가 그대로 최상위에 옵니다.

목록 items[] 요소와 단건 응답은 같은 객체입니다. 같은 authId를 두 경로로 조회하면 같은 field 집합이 돌아옵니다.
삭제된 submission은 deleteTime에 값을 담아 반환합니다.

5-2. 실패

단건 조회에 실패하면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다.

다른 FaceAuth 프로젝트의 submission도 존재하지 않는 authId와 동일하게 404를 반환합니다. 응답으로는 두 경우를 구분할 수 없습니다.

6. 오류 응답

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

HTTP status	code	발생 조건
`400`	`REQUEST_INVALID`	`authId` path parameter가 유효하지 않은 경우
`403`	`AUTH_FORBIDDEN`	API key는 유효하지만 FaceAuth 프로젝트에 연결되지 않은 경우
`404`	`FACEAUTH_SUBMISSION_NOT_FOUND`	해당 프로젝트에서 `authId`를 찾을 수 없는 경우
`503`	`UPSTREAM_UNAVAILABLE`	조회에 필요한 내부 서비스를 일시적으로 사용할 수 없는 경우. 잠시 후 동일 요청을 재시도합니다
`503`	`UPSTREAM_INVALID_RESPONSE`	내부 조회 결과가 공개 계약으로 변환할 수 없는 경우
`500`	`INTERNAL_UNEXPECTED`	예상하지 못한 서버 오류

FaceAuth 시작하기

FaceAuth는 ID check 인증 과정에서 승인된 유저의 셀피 사진과 FaceAuth 과정에서 획득한 셀피 사진을 비교하여 본인 여부를 한 단계 더 검증하는 절차입니다. 제공 방식(URL / API), FaceAuth URL의 쿼리 스트링 구조, 요청 파라미터 정의를 다룹니다.

FaceAuth 결과 웹훅

faceAuth 인증이 완료된 후 최종 결과(approved 또는 rejected)를 기존 ID check 프로젝트의 Webhook URL로 자동 전송하여 실시간 알림을 제공합니다.

애드온

FaceAuth

1. Base URL

2. 인증

3. 요청 예시

4. Path 파라미터

5. 응답

5-1. 성공

5-2. 실패

6. 오류 응답

관련 문서

FaceAuth 시작하기

FaceAuth 결과 웹훅

​1. Base URL

​2. 인증

​3. 요청 예시

​4. Path 파라미터

​5. 응답

​5-1. 성공

​5-2. 실패

​6. 오류 응답

​관련 문서

FaceAuth 시작하기

FaceAuth 결과 웹훅

1. Base URL

2. 인증

3. 요청 예시

4. Path 파라미터

5. 응답

5-1. 성공

5-2. 실패

6. 오류 응답

관련 문서