# API 키 관리하기

Source: https://help.didit.me/ko/account-organization/api-keys
Updated: 2026-10-12

개발자 → API 키에서 키를 확인하고 만들며, 서비스마다 필요한 권한만 가진 별도 키를 발급합니다. 키는 서버에만 보관하세요.

현재 선택된 애플리케이션을 기준으로 하는 **개발자 → API 키** 화면입니다. 모든 애플리케이션에는
**기본** 키가 있으며, 서비스마다 하나씩 키를 더 만들 수 있고 각 키는 고유한 접근 권한과 만료 기간을 가집니다.
키는 서버 측 시크릿이므로 프런트엔드 코드나 앱 번들에는 절대 넣지 마세요.

[Video: API 키 설정 및 웹훅 테스트 - Didit Academy](https://www.youtube.com/watch?v=thOMIGbNLP0&t=38)

[Video: 5단계로 끝내는 KYC API 연동, Cursor용 AI 설정 프롬프트 포함 - Didit Academy](https://www.youtube.com/watch?v=kTAarcImy7E)

API 키는 콘솔의 **개발자 → API 키**에 있으며, 현재 작업 중인 애플리케이션을 기준으로 합니다. 모든 키를 비밀번호처럼 다루세요. 해당 애플리케이션 이름으로 API에 접근할 수 있는 권한을 부여하기 때문입니다.

## 키 찾기

1. **비즈니스 콘솔에 로그인**

   [business.didit.me](https://business.didit.me)로 이동해 로그인합니다.

2. **애플리케이션 선택**

   사이드바 상단의 애플리케이션 카드에서 애플리케이션을 선택합니다. 애플리케이션마다 고유한 키를 가집니다.

3. **개발자에서 API 키 열기**

   **키** 탭에 **기본** 키를 시작으로 모든 키가 나열되며, 각 키의 접근 권한, 마지막 사용 시점, 만료 시점이 표시됩니다.

![키 목록이 표시된 Didit 콘솔의 API 키 페이지](https://help.didit.me/screenshots/api-keys-light.webp)

*이 애플리케이션의 모든 키: 기본 키가 먼저, 그다음 직접 만든 키가 표시됩니다.*

## 키 생성하기

Didit을 호출하는 서비스마다 별도의 키를 주세요. 그래야 각 키가 무엇을 하는지 확인할 수 있고, 그 키만 따로 취소할 수 있습니다.

1. **키 생성 누르기**

   **개발자 → API 키**에서 누릅니다.

2. **이름을 정하고 환경 선택하기**

   키를 사용할 서비스의 이름을 따서 키 이름을 정하고, **라이브**(실제 인증, 요금 부과) 또는 **샌드박스**(테스트 데이터, 요금 없음, 키는 조직의 샌드박스 애플리케이션에 생성됨)를 선택한 다음, 만료 시점을 고릅니다. 만료 없음, 30일, 90일, 1년 후, 또는 직접 고른 날짜 중에서 선택할 수 있습니다.

3. **접근 권한 선택하기**

   **전체 접근**은 모든 것을 읽고 쓸 수 있으며, 자체 백엔드용입니다. **읽기 전용**은 세션, 결정, 미디어를 볼 수 있지만 아무것도 변경할 수 없으며, 결과만 필요한 파트너용입니다. **사용자 지정**은 리소스별로 직접 고를 수 있습니다. 서비스에 신분증 이미지, 셀카, 동영상, PDF 보고서가 아닌 결정만 필요하다면 **미디어 포함**을 해제하세요.

4. **검토하고 시크릿 복사하기**

   전체 시크릿은 키를 생성할 때 한 번만 표시됩니다. 바로 시크릿 관리 도구에 복사하세요.

**기본** 키는 애플리케이션의 원래 시크릿입니다. 항상 전체 접근 권한을 가지며, 교체할 수는 있지만 취소할 수는 없습니다.

## API 키와 서명 시크릿은 다른 것입니다

혼동하면 헷갈리는 오류가 발생하므로 분명히 짚어둘 가치가 있습니다.

| | 용도 | 단위 |
|---|---|---|
| **API 키** | `x-api-key` 헤더로 Didit 호출을 인증하는 용도 | 애플리케이션 단위, 필요한 만큼 |
| **Webhook 서명 시크릿** | 수신한 webhook이 실제로 Didit에서 온 것인지 검증하는 용도 | webhook **엔드포인트** 단위 |

서명 시크릿을 API 키로 보내면 401이 발생합니다. API 키로 webhook을 검증하려 하면 서명 불일치가 발생합니다. 둘 다 흔한 실수입니다.

> **Warning:** API 키는 시크릿입니다. 프런트엔드 코드, 공개 저장소, 모바일 앱 번들에는 절대 넣지 마세요. 서버 측에서만 보관하세요. 배포된 앱 번들에 들어 있는 키는 이미 공격자 손에 있는 키나 마찬가지입니다.
> [API 인증](https://docs.didit.me/getting-started/api-authentication)을 참고하세요.

## 테스트용 키 받기

프로덕션 환경을 대상으로 테스트하지 마세요. 콘솔을 **샌드박스**로 전환한 다음 그곳에서 키를 만들거나, 키를 만들 때 환경으로 **샌드박스**를 선택하세요. 샌드박스 세션은 외부 체크를 모두 모의 처리하며, 요금이 청구되지 않고, 실제 사용자 데이터를 다루지도 않습니다.

키는 하나의 애플리케이션에 속하며, 따라서 그 애플리케이션의 환경에도 속합니다. 샌드박스 키로는 절대 라이브 인증이 생성되지 않고, 라이브 키로는 절대 샌드박스 인증이 생성되지 않습니다. 시크릿을 보관하는 곳에서 키 이름을 명확히 구분해 두는 것이 좋습니다. [sandbox에서 테스트하기](https://help.didit.me/ko/getting-started/sandbox-and-testing)를 참고하세요.

## 키 회전하기

키가 노출됐을 가능성이 있다면 키를 열고 **키 교체**를 선택하세요. 새 시크릿이 발급되고, 기존 시크릿은 **24시간** 동안 계속 작동하므로 중단 없이 새 시크릿을 배포할 수 있습니다. 그 이후에는 기존 시크릿으로 보낸 모든 요청이 401을 반환합니다.

키를 지금 당장 중지해야 한다면 대신 **키 취소**를 선택하세요. 취소하면 즉시 중지되며 되돌릴 수 없습니다. 기본 키는 교체만 할 수 있습니다.

정기적인 회전은 좋은 습관입니다. 단순한 클릭이 아니라 배포처럼 계획하세요.

## 401과 403 해결하기

| 오류 | 원인 | 해결 방법 |
|---|---|---|
| `401` | 키가 없거나, 형식이 잘못됐거나, 만료됐거나, 취소됐거나, 교체된 지 24시간이 지났음 | 해당 애플리케이션의 **개발자 → API 키**에서 키를 확인하세요. 불필요한 공백이나 따옴표가 들어가지 않았는지, 서명 시크릿을 잘못 붙여넣지 않았는지 확인하세요 |
| `403` | 키는 유효하지만 이 호출은 허용되지 않음 | 대개 애플리케이션을 잘못 지정했거나, 라이브 키에 sandbox 전용 필드를 사용했거나(또는 그 반대), 키에 주어지지 않은 접근 권한이 필요하거나(예: 읽기 전용 키로 쓰기를 시도), 계정에서 활성화되지 않은 기능인 경우입니다 |

특정 워크플로우에서 발생하는 `403`은 거의 항상 그 키가 해당 워크플로우를 소유한 애플리케이션과 **다른 애플리케이션**의 키라는 뜻입니다. 콘솔에서 애플리케이션을 전환하고 그쪽 키 중 하나를 사용하세요. 전체 정리는 [API 오류와 그 의미](https://help.didit.me/ko/integration/api-errors)를 참고하세요.

## 키로 할 수 있는 일 제한하기

키를 생성할 때 접근 권한을 선택하고, 나중에 **접근 권한 편집**으로 변경할 수 있습니다(시크릿은 그대로 유지되며, 기본 키의 접근 권한은 편집할 수 없습니다). **읽기 전용**은 파트너가 아무것도 변경하지 못하게 하고, **사용자 지정**은 리소스(세션, 결정, 미디어, 개인, 기업 등)별로 없음, 읽기, 쓰기를 설정하며, **미디어 포함**을 꺼 두면 서비스가 신분증 이미지, 셀카, 동영상, PDF 보고서를 다운로드하지 못합니다. **제한**에서는 키를 일부 워크플로우, 승인된 세션만, 또는 IP 주소 목록으로 제한할 수도 있습니다. 목록 밖에서 온 요청은 403으로 응답하고, 키의 워크플로우나 상태 범위 밖에 있는 세션은 404로 응답합니다. 키를 열면 그 키로 정확히 무엇을 할 수 있는지 확인할 수 있습니다. 키는 접근 권한이 허용하는 범위를 넘어 작동할 수 없습니다.

## 팀 내에서 키를 볼 수 있는 사람

키 표시 여부는 역할을 따릅니다. 이 페이지를 보려면 API 키 읽기 권한이 필요하며, **개발자** 역할에는 이 권한이 포함되어 있습니다. 시크릿은 콘솔에서 항상 가려진 상태로 표시됩니다. 팀원이 이 페이지를 찾지 못한다면 문제를 제기하기 전에 역할부터 확인하세요. [팀원 초대와 역할 설정](https://help.didit.me/ko/account-organization/team-members-and-roles)을 참고하세요.

## 모든 호출이 기록됩니다

API 키로 이루어진 요청은 사람이 아니라 키 이름으로 **감사 로그**에 표시됩니다. 그렇기 때문에 여러 서비스가 키 하나를 공유하면 사고 발생 시 조사가 더 어려워집니다. 이용 주체마다 키를 하나씩 두는 편이 파악하기 쉽습니다. [감사 로그 사용하기](https://help.didit.me/ko/account-organization/audit-logs)를 참고하세요.