API 인증: 안전한 KYC API 요청 가이드

API 키 확인하기

Didit에서 API 키는 계정 내 특정 애플리케이션으로 범위가 지정됩니다. 애플리케이션은 특정 프로젝트 또는 환경에 맞게 워크플로를 구성하고 인증을 관리할 수 있는 작업 공간입니다. 애플리케이션을 생성하면 전체 접근 권한을 가진 기본 API 키가 부여됩니다. 그 외에도 서비스나 파트너에 필요한 권한만 가진 추가 키를 생성할 수 있습니다. 키를 확인하는 방법은 다음과 같습니다:

Business Console에 로그인

Didit Business Console로 이동하여 로그인합니다.

애플리케이션 선택

상단 드롭다운 메뉴에서 작업할 애플리케이션을 선택합니다.

API 키 열기

왼쪽 사이드바에서 Developers -> API keys로 이동합니다.

키 복사 또는 생성

기본 키는 애플리케이션 자체의 비밀 키입니다. 서비스나 파트너에게 필요한 권한만 부여된 자체 비밀 키를 제공하려면 새 키를 생성하세요.

API 키는 비밀 정보이므로 비밀번호처럼 안전하게 다루어야 합니다.기본 키는 애플리케이션을 대신하여 API에 대한 전체 접근 권한을 제공합니다. 프론트엔드 코드, 공개 저장소 또는 클라이언트 측 번들에 절대 노출해서는 안 됩니다. 항상 서버 측에만 보관하세요.

API 키 형식

새 API 키는 프로덕션 환경 애플리케이션의 경우 sk_live_, 샌드박스 애플리케이션의 경우 sk_test_로 시작하며, 그 뒤에 URL에서 사용할 수 있는 43개의 문자(영문자, 숫자, -, _)가 이어집니다. 이 형식 도입 이전에 생성된 키에는 접두사가 없으며 기존과 동일하게 계속 작동합니다. 접두사를 포함한 전체 키를 x-api-key 헤더로 전송해야 하며, 접두사가 없다는 이유로 키를 거부하지 마세요.

조직 ID 확인하기

조직 ID는 조직을 식별하는 UUID입니다. /auth/v2/organizations/me/{org_id}/applications/와 같이 조직 범위의 API 경로에서 사용합니다. API 호출 없이 Business Console에서 바로 복사할 수 있습니다:

조직 설정 열기

Didit Business Console에서 조직 설정으로 이동합니다.

조직 ID 복사

조직 ID 필드에는 조직 이름 옆에 조직의 UUID와 클립보드 복사 버튼이 표시됩니다.

인증된 요청 보내기

API 요청을 인증하려면 비밀 API 키를 x-api-key HTTP 헤더에 포함하세요. 다음은 Create Session endpoint에 대한 인증된 요청의 예시입니다:

cURL

curl --request POST \
     --url https://verification.didit.me/v3/session/ \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'x-api-key: YOUR_API_KEY' \
     --data '
{
  "workflow_id": "WORKFLOW_ID",
  "vendor_data": "USER_ID",
  "callback": "CALLBACK_URL"
}
'

에러 처리

API 키가 올바르지 않거나 형식이 잘못되었거나 취소된 경우, API는 401 Unauthorized를 반환합니다:

{
  "detail": "Authentication credentials were not provided or are invalid."
}

만료된 키 역시 "detail": "This API key has expired."와 함께 401을 반환합니다. 키가 없는 요청은 "detail": "You do not have permission to perform this action."과 함께 403을 반환합니다.

상태 코드	의미
401	API 키가 올바르지 않거나 형식이 잘못되었거나 취소되었거나 만료됨
403	API 키가 전송되지 않았거나, 키에 요청한 리소스 또는 작업에 대한 권한이 없거나, 키의 IP 목록 외의 주소에서 요청이 수신됨
`"code": "application_deleted"`가 포함된 403	키가 삭제된 애플리케이션에 속해 있습니다. API는 삭제 후 몇 분 동안 이 응답을 반환한 다음, 유효하지 않은 키와 마찬가지로 키를 거부합니다. 애플리케이션과 해당 키가 더 이상 존재하지 않으므로 재시도하지 마세요.
404	세션 경로의 경우: 세션이 키의 워크플로 또는 상태 범위를 벗어남

API 에러 페이지에 모든 상태, 본문 및 코드가 나열되어 있습니다.

범위 지정 API 키

기본 키를 공유하는 대신 각 서비스나 파트너에 자체 키를 부여하세요. 각 키에는 고유한 접근 권한이 있습니다. 모든 리소스(세션, 결정, 미디어, 개인, 기업, 거래, 워크플로, webhook, 애플리케이션 설정, 분석)에 대해 없음, 읽기 또는 쓰기 권한을 설정할 수 있으며, 특정 워크플로, 승인된 세션만, IP 주소 목록 및 만료일로 선택적 제한을 둘 수 있습니다. 24시간의 중복 기간을 두고 키를 교체할 수 있으며, 즉시 취소할 수도 있습니다. 범위 지정 접근 기능이 도입되기 전에 생성된 키는 전체 접근 권한을 유지합니다. 사전 설정, 각 항목이 다루는 리소스, API가 범위 지정 키에 응답하는 방식에 대한 자세한 내용은 API 키를 참조하세요.

401 에러가 발생하는 경우 올바른 애플리케이션에 대한 올바른 API 키를 사용하고 있는지, 그리고 키가 재생성되지 않았는지 다시 한번 확인하세요.

개요

요금

워크플로 및 인증

검토 및 운영

엔터티(사용자 및 기업)

설정 및 사용자 지정

보안 및 컴플라이언스

Didit Academy

리소스

API 인증: 안전한 KYC API 요청 가이드

API 키 확인하기

API 키 형식

조직 ID 확인하기

인증된 요청 보내기

에러 처리

범위 지정 API 키

​API 키 확인하기

​API 키 형식

​조직 ID 확인하기

​인증된 요청 보내기

​에러 처리

​범위 지정 API 키

API 키 확인하기

API 키 형식

조직 ID 확인하기

인증된 요청 보내기

에러 처리

범위 지정 API 키