나이 확인 (Age Verification)

k-ID는 다음 시나리오에 대해 사용자의 나이를 확인할 수 있는 API 세트를 제공합니다.

API	시나리오
/age-verification/perform-access-age-verification	기능, 성인용 콘텐츠 또는 제품 자체에 대한 액세스 전에 사용자의 나이를 확인
/age-verification/perform-trusted-adult-verification	검증 가능한 부모 동의(VPC)를 위해 신뢰할 수 있는 성인(부모 또는 보호자) 확인 수행
/age-verification/perform-facial-age-estimation	얼굴 나이 추정만으로 나이 확인 수행
/age-verification/perform-id-verification	정부 발급 신분증 확인만으로 나이 확인 수행
/age-verification/perform-age-appeal	미성년자로 의심되는 사용자의 제품 접근 복구 전 나이 확인

Age Verification API는 요청 및 응답 형식이 표준화되어 있습니다.

요청 본문 (Request Body)

속성	설명	필수 여부
jurisdiction	나이 확인이 이루어져야 하는 관할권	예
criteria	나이 확인 기준	예
subject.email	사용자가 다른 컨텍스트에서 이메일로 k-ID에서 나이를 확인한 적이 있다면, 다시 추정/증명 요구 없이 기존 나이를 반환	아니오
subject.claimedAge	나이 게이트에서 사용자가 입력한 나이. 나이 추정 과정에 참고로 사용	아니오
subject.id	다중 시도 실패 보고에 사용하는 식별자(임시 세션 ID 또는 해시된 사용자 ID 등)	아니오

예시:

{
  "jurisdiction": "US-CA",
  "subject": {
    "email": "user@example.com",
    "claimedAge": 23,
    "id": "3854909b-8888-4bed-9282-24b74c4a3c97"
  },
  "criteria": {
    "ageCategory": "DIGITAL_YOUTH_OR_ADULT"
  }
}

응답 본문 (Response Body)

성공적인 요청은 다음 구조의 응답을 반환합니다.

속성	설명
id	Age Verification 서비스가 생성한 고유 확인 ID
url	사용자가 자기 확인을 수행하기 위해 표시해야 하는 나이 확인 URL

예시:

{
  "id": "7854909b-9124-4bed-9282-24b44c4a3c97",
  "url": "https://family.k-id.com/verify?token=eyJhbGciOi..."
}

Verification Result

사용자가 나이 확인을 성공적으로 완료했거나, 최대 재시도 횟수에 도달했지만 성공하지 못한 경우, 결과는 두 가지 방식으로 전달됩니다.

1. 등록된 웹훅으로 Verification.Result 이벤트가 전송됩니다.
2. 위 응답의 URL을 iFrame으로 포함한 경우, 부모 프레임으로 window 메시지(MessageEvent)가 전송됩니다.

window 메시지 접근 예시:

const handleMessage = (event: MessageEvent) => {
  const message = event.data;
  if (message.eventType === "Verification.Result") {
    // 결과 처리 로직
    console.log("eventData", message);
  }
};

window.addEventListener("message", handleMessage);

window 이벤트와 웹훅 이벤트의 data 요소에는 다음 속성이 포함됩니다.

속성	설명
id	이번 결과가 속한 확인 ID
status	사용자가 나이 기준을 충족했는지 여부에 따라 PASS 또는 FAIL
ageCategory	요청에 지정된 관할권에서 사용자가 속한 나이 카테고리. 지원 값: adult, digital-youth, digital-minor
method	사용된 확인 방법. 지원 값: id-document, age-estimation, age-attestation, credit-card, social-security-number
failureReason	실패 사유. 지원 값: age-criteria-not-met, max-attempts-exceeded, fraudulent-activity-detected (단, status가 FAIL인 경우에만 설정)
age	추정되거나 확인된 나이의 하한/상한을 low/high로 반환

예시:

{
  "eventType": "Verification.Result",
  "data": {
    "id": "5a58e98a-e477-484b-b36a-3857ea9daaba",
    "status": "PASS",
    "ageCategory": "adult",
    "method": "id-document",
    "age": {
      "low": 25,
      "high": 25
    }
  }
}

window 이벤트 처리 예시:

const handleMessage = (event: MessageEvent) => {
  const message = event.data;
  if (message.eventType === "Verification.Result" && ) {
    if (message.data.status === "PASS") {
      window.location.href = `https://www.example.com/success?verificationId=${message.data.id}`
    }
    if (message.data.status === "FAIL") {
      window.location.href = `https://www.example.com/fail?verificationId=${message.data.id}`
    }
  }
};

window.addEventListener("message", handleMessage);

Verification Error

예상치 못한 오류가 발생한 경우, 구현이 우아하게 처리할 수 있도록 Javascript 이벤트가 발생합니다.

메시지 예시:

{
  "eventType": "Verification.Error",
  "method": "credit-card",
  "status": "ERROR"
}

확인 상태 조회 (Checking Verification Status)

Javascript 이벤트와 k-ID 웹훅 전송 외에도, 확인 건에 대한 상태를 조회할 수 있습니다. 이는 등록된 웹훅이 일시적으로 도달 불가였던 상황 등으로 상태 이벤트를 수신하지 못한 경우에 유용합니다. 상태 조회는 /age-verification/get-status API를 사용합니다. 반환되는 데이터 구조는 웹훅으로 전송되는 data 요소와 동일합니다.

지원되는 확인 방법 (Supported Verification Methods)

제품, 기능 또는 콘텐츠에 대한 액세스 용도라면, k-ID는 사용자의 나이를 확인하기 위한 다양한 방법을 제공합니다.

방법	설명
age-estimation	개인정보 보호형 얼굴 나이 추정. 생체 정보는 사용자 기기를 벗어나지 않음
id-verification	여권, 운전면허증 등 정부 발급 신분증을 사용한 나이 확인
age-attestation	검증된 부모가 자녀의 나이를 보증

k-ID는 신뢰할 수 있는 성인 확인용 증명 방법도 제공합니다. 또한 일부 방법(예: age-estimation)은 특정 관할권의 신뢰 성인 확인 용도로 허용되지 않을 수 있습니다.

방법	설명
credit-card	성인이 유효한 신용카드를 제시해 계약 연령임을 증명
social-security-number	사회보장번호와 일부 개인정보 조합으로 나이를 증명

Age Verification 통합 테스트

k-ID API 호출 코드를 작성하기 전에, API 키와 API 문서를 사용해 직접 얼굴 나이 추정을 시도할 수 있습니다.

먼저 간단한 k-ID API 호출 만들기 단계를 따르세요.

그런 다음 같은 브라우저 창에서 /age-verification/perform-facial-age-estimation 호출을 실행합니다. 목록에서 해당 API를 클릭하세요.

이후 Try it out 버튼을 클릭하고, Execute 버튼을 클릭하세요.

앱(또는 별도 브라우저 창)에서 사용할 iFrame URL은 응답의 url 매개변수에 포함됩니다. 해당 URL을 브라우저에 붙여 넣으세요. 예시는 다음과 같습니다:

https://family.k-id.com/verify?token=...

이후 안내 페이지가 표시됩니다:

Start 버튼을 클릭해 직접 얼굴 나이 추정을 시도해 보세요. 보안을 위해 필요한 생존감지(liveness) 점검에 유의하세요. 이 데모에서는 결과가 화면에 직접 표시되지 않고 Javascript 이벤트 및 웹훅 호출로 전송됩니다. 카메라 정보는 이 데모에서 사용자 기기를 벗어나지 않습니다.