GET/Face-auth (목록) - ARGOS Identity

엔드포인트가 /v3/face-auth로 변경되었습니다.구 엔드포인트 /v3/faceauth와 path·응답 구조·필드 이름이 모두 다릅니다. 기존 연동을 옮기려면 FaceAuth 공통 참조 — 구 API에서 옮기기를 확인하세요.특정 건 하나를 조회하려면 GET/Face-auth/{authId}를 사용하세요. 목록과 단건은 별도 endpoint입니다.

FaceAuth 제출 목록을 최신 생성 시각 순으로 조회합니다. 다음 페이지가 있으면 응답의 nextCursor를 동일한 조건의 후속 요청에 전달하세요.

1. Base URL

GET/Face-auth

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

2. 인증

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

x-api-key

x-api-key: {yourAPIKey}

기존 라이브폼 API Key와는 다른 별도의 API Key가 필요합니다. 애드온 시작하기 — 애드온 API 키 확인하기에서 확인할 수 있습니다.

3. 요청 예시

GET/Face-auth

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

기간을 지정해 조회할 수 있습니다. startDate와 endDate는 반드시 함께 전달해야 합니다.

기간 지정

curl -X GET "https://rest-api.argosidentity.com/v3/face-auth?startDate=2026-08-01T00%3A00%3A00.000Z&endDate=2026-08-31T23%3A59%3A59.999Z&limit=100" \
  -H "x-api-key: {yourAPIKey}"

4. 요청 파라미터

integer

반환할 최대 건수입니다. 기본값은 100이고 최소 10, 최대 200입니다.

string

직전 목록 응답의 nextCursor 값입니다. 서버가 발급한 값을 그대로 전달하세요. 값에 서명이 포함돼 있어 일부라도 수정하면 400 REQUEST_INVALID가 반환됩니다. 직접 조립하거나 다른 조회 조건에 재사용할 수 없습니다.

string

조회 시작 시각입니다. yyyy-MM-dd'T'HH:mm:ss.SSSZ RFC 3339 UTC 형식이며 endDate와 함께 전달해야 합니다.

string

조회 종료 시각입니다. RFC 3339 UTC 형식이며 startDate보다 빠를 수 없습니다. 시작·종료 시각은 모두 조회 범위에 포함됩니다.

위 네 가지 외의 query parameter를 전달하면 400 REQUEST_INVALID가 반환됩니다. 특정 건을 조회하려면 단건 조회 path를 사용하세요.
cursor를 사용한 후속 요청은 첫 요청과 같은 limit, startDate, endDate 를 사용해야 합니다.

5. 응답

result.json

{
  "items": [
    {
      "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-active",
            "error": null
          }
        ]
      },
      "rejectComment": null,
      "failCode": null
    },
    {
      "authId": "sampleAuthId2",
      "authStatus": "rejected",
      "createTime": "2026-08-11T09:10:00.000Z",
      "submitType": "api",
      "kycSubmissionId": "sampleKycSubmissionId2",
      "deleteTime": null,
      "policy": {
        "faceSimilarity": { "enabled": true, "threshold": 85 },
        "occluded": { "enabled": true, "threshold": null },
        "faceCover": { "enabled": false, "threshold": null },
        "headCover": { "enabled": false, "threshold": null },
        "liveness": { "enabled": false, "threshold": null },
        "activeLiveness": { "enabled": false, "threshold": null }
      },
      "result": {
        "faceSimilarity": 72.4,
        "livenessScore": null,
        "activeLivenessScore": null,
        "occluded": {
          "value": false,
          "confidence": 99.2
        },
        "faceCover": null,
        "headCover": null
      },
      "signals": null,
      "rejectComment": [
        "face compare similarity score is lower than threshold"
      ],
      "failCode": [
        "face_compare_underscore"
      ]
    }
  ],
  "nextCursor": "v1.eyJ2IjoxLCJjcmVhdGVUaW1l..."
}

5-1. 성공

목록 조회에 성공하면 200 OK와 아래 본문이 돌아옵니다.

array

조회 결과 배열입니다. 각 요소는 FaceAuthSubmission 객체입니다. 조건에 맞는 건이 없으면 빈 배열입니다.

nullable · string

다음 page 요청의 cursor parameter에 전달할 값입니다. 다음 page가 없으면 null입니다.서명이 포함된 토큰이며 v1.{payload}.{signature} 형식입니다. payload는 마지막 항목의 위치와 조회 조건을 담고 있고 base64로 인코딩돼 있어 디코딩이 가능하지만, 서명이 조회 조건에 묶여 있어 값을 바꾸거나 다른 조건으로 재사용하면 검증에 실패합니다. 구조에 의존하지 말고 받은 값을 그대로 전달하세요. 형식은 사전 고지 없이 바뀔 수 있습니다.

응답 본문의 최상위 field는 items와 nextCursor 둘뿐입니다.
목록에는 삭제된 submission도 포함될 수 있습니다. 삭제 완료 건은 deleteTime에 값이 있습니다.

5-2. 실패

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

6. 오류 응답

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

HTTP status	code	발생 조건
`400`	`REQUEST_INVALID`	유효하지 않은 `limit`, 날짜 범위, cursor 또는 미정의 query parameter를 전달한 경우
`403`	`AUTH_FORBIDDEN`	API key는 유효하지만 FaceAuth 프로젝트에 연결되지 않은 경우
`503`	`UPSTREAM_UNAVAILABLE`	조회에 필요한 내부 서비스를 일시적으로 사용할 수 없는 경우. 잠시 후 동일 요청을 재시도합니다
`503`	`UPSTREAM_INVALID_RESPONSE`	내부 조회 결과가 공개 계약으로 변환할 수 없는 경우
`500`	`INTERNAL_UNEXPECTED`	예상하지 못한 서버 오류

​1. Base URL

​2. 인증

​3. 요청 예시

​4. 요청 파라미터

​5. 응답

​5-1. 성공

​5-2. 실패

​6. 오류 응답

1. Base URL

2. 인증

3. 요청 예시

4. 요청 파라미터

5. 응답

5-1. 성공

5-2. 실패

6. 오류 응답