API 키 관리하기
콘솔의 API & Webhooks에서 API 키를 확인하고, 서버 측에만 보관하며, 테스트에는 별도의 sandbox 애플리케이션을 사용하고, 401 및 403 오류를 해결하는 방법입니다.
현재 선택된 애플리케이션을 기준으로 하는 API & Webhooks 화면입니다. 애플리케이션마다 키가 하나씩 있으며, 그 키 자체가 곧 환경입니다. 라이브 애플리케이션에 별도의 테스트 키는 없습니다. 이 키는 서버 측 시크릿이므로 프런트엔드 코드나 앱 번들에는 절대 넣지 마세요.
API 키는 콘솔 사이드바의 API & Webhooks에 있으며, 현재 작업 중인 애플리케이션을 기준으로 합니다. 비밀번호처럼 다루세요. 해당 애플리케이션 이름으로 API에 완전히 접근할 수 있는 권한을 부여하기 때문입니다.
#키 찾기
- 비즈니스 콘솔에 로그인
business.didit.me로 이동해 로그인합니다.
- 애플리케이션 선택
콘솔 상단 드롭다운에서 원하는 애플리케이션을 선택합니다. 애플리케이션마다 고유한 키를 가집니다.
- API & Webhooks 열기
이곳에 API 키가 있으며, webhook 대상 주소와 그 서명 시크릿도 함께 있습니다.
- Create API key로 새 키를 발급합니다. 키는 애플리케이션 단위입니다.
- 시크릿은 여기서 한 번만 표시됩니다. 자체 시크릿 저장소에 복사해 두세요.
- Rotate secret은 키 이름은 그대로 두고 시크릿만 교체합니다.
- Last used를 보면 폐기하기 전에 그 키가 실제로 쓰이고 있는지 잊혀진 것인지 알 수 있습니다.
#API 키와 서명 시크릿은 다른 것입니다
혼동하면 헷갈리는 오류가 발생하므로 분명히 짚어둘 가치가 있습니다.
| 용도 | 단위 | |
|---|---|---|
| API 키 | x-api-key 헤더로 Didit 호출을 인증하는 용도 | 애플리케이션 단위 |
| Webhook 서명 시크릿 | 수신한 webhook이 실제로 Didit에서 온 것인지 검증하는 용도 | 대상 주소 단위 |
서명 시크릿을 API 키로 보내면 401이 발생합니다. API 키로 webhook을 검증하려 하면 서명 불일치가 발생합니다. 둘 다 흔한 실수입니다.
API 키는 시크릿입니다. 프런트엔드 코드, 공개 저장소, 모바일 앱 번들에는 절대 넣지 마세요. 서버 측에서만 보관하세요. 배포된 앱 번들에 들어 있는 키는 이미 공격자 손에 있는 키나 마찬가지입니다. API 인증을 참고하세요.
#테스트용 키 받기
프로덕션 환경을 대상으로 테스트하지 마세요. sandbox 모드로 별도의 애플리케이션을 만드세요. sandbox 세션은 외부 체크를 모두 모의 처리하며, 요금이 청구되지 않고, 실제 사용자 데이터를 다루지도 않습니다. 개발하는 동안은 sandbox 키를 사용하고, 실제 인증을 위한 라이브 애플리케이션은 따로 유지하세요.
라이브 애플리케이션에는 "테스트 키"라는 개념이 없습니다. 키 자체가 환경이므로, 시크릿을 보관하는 곳에서 키 이름을 명확히 구분해 두는 것이 좋습니다. sandbox에서 테스트하기를 참고하세요.
#키 회전하기
키가 노출됐을 가능성이 있다면 같은 API & Webhooks 페이지에서 재발급하세요. 재발급하면 기존 키가 즉시 무효화되므로, 버튼을 누르는 순간 프로덕션 트래픽이 실패하기 시작하지 않도록 사용 중인 모든 곳을 먼저 업데이트하세요.
정기적인 회전은 좋은 습관입니다. 단순한 클릭이 아니라 배포처럼 계획하세요.
#401과 403 해결하기
| 오류 | 원인 | 해결 방법 |
|---|---|---|
401 | 키가 없거나, 형식이 잘못됐거나, 재발급됐음 | 해당 애플리케이션의 API & Webhooks에서 현재 키를 복사하세요. 불필요한 공백이나 따옴표가 들어가지 않았는지, 서명 시크릿을 잘못 붙여넣지 않았는지 확인하세요 |
403 | 키는 유효하지만 이 호출은 허용되지 않음 | 대개 애플리케이션을 잘못 지정했거나, 라이브 키에 sandbox 전용 필드를 사용했거나(또는 그 반대), 키에 필요한 권한이 없거나, 계정에서 활성화되지 않은 기능인 경우입니다 |
특정 워크플로우에서 발생하는 403은 거의 항상 그 키가 해당 워크플로우를 소유한 애플리케이션과 다른 애플리케이션의 키라는 뜻입니다. 콘솔에서 애플리케이션을 전환하고 그쪽 키를 복사하세요. 전체 정리는 API 오류와 그 의미를 참고하세요.
#키로 할 수 있는 일 제한하기
키가 접근할 수 있는 데이터 범주를 제한하고 싶다면 - 예를 들어 특정 서비스가 문서 이미지를 가져오지 못하게 하려면 - 이는 키 설정이 아니라 권한 문제이며, 사용 가능 여부는 계정에 따라 다릅니다. 키에 제한이 없다고 가정하거나 제한이 있다고 가정하지 말고, 둘 다 반대 방향으로 위험하니 지원팀에 문의하세요.
#팀 내에서 키를 볼 수 있는 사람
키 표시 여부는 역할을 따릅니다. Developer 역할은 API 키를 포함하지만 Reader는 포함하지 않습니다. 팀원이 이 페이지를 찾지 못한다면 문제를 제기하기 전에 역할부터 확인하세요. 팀원 초대와 역할 설정을 참고하세요.
#모든 호출이 기록됩니다
API 키로 이루어진 요청은 사람이 아니라 애플리케이션 이름으로 Audit Logs에 표시됩니다. 그렇기 때문에 여러 서비스가 키 하나를 공유하면 사고 발생 시 조사가 더 어려워집니다. 이용 주체마다 키를 하나씩 두는 편이 파악하기 쉽습니다. 감사 로그 사용하기를 참고하세요.