개발자 → API 키에서 키를 확인하고 만들며, 서비스마다 필요한 권한만 가진 별도 키를 발급합니다. 키는 서버에만 보관하세요.
현재 선택된 애플리케이션을 기준으로 하는 개발자 → API 키 화면입니다. 모든 애플리케이션에는 기본 키가 있으며, 서비스마다 하나씩 키를 더 만들 수 있고 각 키는 고유한 접근 권한과 만료 기간을 가집니다. 키는 서버 측 시크릿이므로 프런트엔드 코드나 앱 번들에는 절대 넣지 마세요.
API 키는 콘솔의 개발자 → API 키에 있으며, 현재 작업 중인 애플리케이션을 기준으로 합니다. 모든 키를 비밀번호처럼 다루세요. 해당 애플리케이션 이름으로 API에 접근할 수 있는 권한을 부여하기 때문입니다.
#키 찾기
- 비즈니스 콘솔에 로그인
business.didit.me로 이동해 로그인합니다.
- 애플리케이션 선택
사이드바 상단의 애플리케이션 카드에서 애플리케이션을 선택합니다. 애플리케이션마다 고유한 키를 가집니다.
- 개발자에서 API 키 열기
키 탭에 기본 키를 시작으로 모든 키가 나열되며, 각 키의 접근 권한, 마지막 사용 시점, 만료 시점이 표시됩니다.
#키 생성하기
Didit을 호출하는 서비스마다 별도의 키를 주세요. 그래야 각 키가 무엇을 하는지 확인할 수 있고, 그 키만 따로 취소할 수 있습니다.
- 키 생성 누르기
개발자 → API 키에서 누릅니다.
- 이름을 정하고 환경 선택하기
키를 사용할 서비스의 이름을 따서 키 이름을 정하고, 라이브(실제 인증, 요금 부과) 또는 샌드박스(테스트 데이터, 요금 없음, 키는 조직의 샌드박스 애플리케이션에 생성됨)를 선택한 다음, 만료 시점을 고릅니다. 만료 없음, 30일, 90일, 1년 후, 또는 직접 고른 날짜 중에서 선택할 수 있습니다.
- 접근 권한 선택하기
전체 접근은 모든 것을 읽고 쓸 수 있으며, 자체 백엔드용입니다. 읽기 전용은 세션, 결정, 미디어를 볼 수 있지만 아무것도 변경할 수 없으며, 결과만 필요한 파트너용입니다. 사용자 지정은 리소스별로 직접 고를 수 있습니다. 서비스에 신분증 이미지, 셀카, 동영상, PDF 보고서가 아닌 결정만 필요하다면 미디어 포함을 해제하세요.
- 검토하고 시크릿 복사하기
전체 시크릿은 키를 생성할 때 한 번만 표시됩니다. 바로 시크릿 관리 도구에 복사하세요.
기본 키는 애플리케이션의 원래 시크릿입니다. 항상 전체 접근 권한을 가지며, 교체할 수는 있지만 취소할 수는 없습니다.
#API 키와 서명 시크릿은 다른 것입니다
혼동하면 헷갈리는 오류가 발생하므로 분명히 짚어둘 가치가 있습니다.
| 용도 | 단위 | |
|---|---|---|
| API 키 | x-api-key 헤더로 Didit 호출을 인증하는 용도 | 애플리케이션 단위, 필요한 만큼 |
| Webhook 서명 시크릿 | 수신한 webhook이 실제로 Didit에서 온 것인지 검증하는 용도 | webhook 엔드포인트 단위 |
서명 시크릿을 API 키로 보내면 401이 발생합니다. API 키로 webhook을 검증하려 하면 서명 불일치가 발생합니다. 둘 다 흔한 실수입니다.
API 키는 시크릿입니다. 프런트엔드 코드, 공개 저장소, 모바일 앱 번들에는 절대 넣지 마세요. 서버 측에서만 보관하세요. 배포된 앱 번들에 들어 있는 키는 이미 공격자 손에 있는 키나 마찬가지입니다. API 인증을 참고하세요.
#테스트용 키 받기
프로덕션 환경을 대상으로 테스트하지 마세요. 콘솔을 샌드박스로 전환한 다음 그곳에서 키를 만들거나, 키를 만들 때 환경으로 샌드박스를 선택하세요. 샌드박스 세션은 외부 체크를 모두 모의 처리하며, 요금이 청구되지 않고, 실제 사용자 데이터를 다루지도 않습니다.
키는 하나의 애플리케이션에 속하며, 따라서 그 애플리케이션의 환경에도 속합니다. 샌드박스 키로는 절대 라이브 인증이 생성되지 않고, 라이브 키로는 절대 샌드박스 인증이 생성되지 않습니다. 시크릿을 보관하는 곳에서 키 이름을 명확히 구분해 두는 것이 좋습니다. sandbox에서 테스트하기를 참고하세요.
#키 회전하기
키가 노출됐을 가능성이 있다면 키를 열고 키 교체를 선택하세요. 새 시크릿이 발급되고, 기존 시크릿은 24시간 동안 계속 작동하므로 중단 없이 새 시크릿을 배포할 수 있습니다. 그 이후에는 기존 시크릿으로 보낸 모든 요청이 401을 반환합니다.
키를 지금 당장 중지해야 한다면 대신 키 취소를 선택하세요. 취소하면 즉시 중지되며 되돌릴 수 없습니다. 기본 키는 교체만 할 수 있습니다.
정기적인 회전은 좋은 습관입니다. 단순한 클릭이 아니라 배포처럼 계획하세요.
#401과 403 해결하기
| 오류 | 원인 | 해결 방법 |
|---|---|---|
401 | 키가 없거나, 형식이 잘못됐거나, 만료됐거나, 취소됐거나, 교체된 지 24시간이 지났음 | 해당 애플리케이션의 개발자 → API 키에서 키를 확인하세요. 불필요한 공백이나 따옴표가 들어가지 않았는지, 서명 시크릿을 잘못 붙여넣지 않았는지 확인하세요 |
403 | 키는 유효하지만 이 호출은 허용되지 않음 | 대개 애플리케이션을 잘못 지정했거나, 라이브 키에 sandbox 전용 필드를 사용했거나(또는 그 반대), 키에 주어지지 않은 접근 권한이 필요하거나(예: 읽기 전용 키로 쓰기를 시도), 계정에서 활성화되지 않은 기능인 경우입니다 |
특정 워크플로우에서 발생하는 403은 거의 항상 그 키가 해당 워크플로우를 소유한 애플리케이션과 다른 애플리케이션의 키라는 뜻입니다. 콘솔에서 애플리케이션을 전환하고 그쪽 키 중 하나를 사용하세요. 전체 정리는 API 오류와 그 의미를 참고하세요.
#키로 할 수 있는 일 제한하기
키를 생성할 때 접근 권한을 선택하고, 나중에 접근 권한 편집으로 변경할 수 있습니다(시크릿은 그대로 유지되며, 기본 키의 접근 권한은 편집할 수 없습니다). 읽기 전용은 파트너가 아무것도 변경하지 못하게 하고, 사용자 지정은 리소스(세션, 결정, 미디어, 개인, 기업 등)별로 없음, 읽기, 쓰기를 설정하며, 미디어 포함을 꺼 두면 서비스가 신분증 이미지, 셀카, 동영상, PDF 보고서를 다운로드하지 못합니다. 제한에서는 키를 일부 워크플로우, 승인된 세션만, 또는 IP 주소 목록으로 제한할 수도 있습니다. 목록 밖에서 온 요청은 403으로 응답하고, 키의 워크플로우나 상태 범위 밖에 있는 세션은 404로 응답합니다. 키를 열면 그 키로 정확히 무엇을 할 수 있는지 확인할 수 있습니다. 키는 접근 권한이 허용하는 범위를 넘어 작동할 수 없습니다.
#팀 내에서 키를 볼 수 있는 사람
키 표시 여부는 역할을 따릅니다. 이 페이지를 보려면 API 키 읽기 권한이 필요하며, 개발자 역할에는 이 권한이 포함되어 있습니다. 시크릿은 콘솔에서 항상 가려진 상태로 표시됩니다. 팀원이 이 페이지를 찾지 못한다면 문제를 제기하기 전에 역할부터 확인하세요. 팀원 초대와 역할 설정을 참고하세요.
#모든 호출이 기록됩니다
API 키로 이루어진 요청은 사람이 아니라 키 이름으로 감사 로그에 표시됩니다. 그렇기 때문에 여러 서비스가 키 하나를 공유하면 사고 발생 시 조사가 더 어려워집니다. 이용 주체마다 키를 하나씩 두는 편이 파악하기 쉽습니다. 감사 로그 사용하기를 참고하세요.
아직 해결되지 않았나요? 담당자와 이야기하세요.
조직 ID와 문의할 세션 ID를 함께 보내 주세요.