API 키 관리, 노출을 막는 보관 원칙과 교체 5단계

API 키 관리는 키를 화면 코드에 넣지 않고 사용 범위를 제한하며, 노출되면 바로 교체하는 것이 원칙입니다. 이 글에서는 홈페이지에 연결된 지도·결제·메일·알림 서비스 키를 안전하게 보관하는 방법과 노출됐을 때의 교체 5단계를 정리했습니다.

API 키가 무엇이고 왜 지켜야 하나

홈페이지는 지도, 결제, 메일 발송, 문자·알림톡, 분석 도구 같은 외부 서비스와 연결됩니다. 이때 외부 서비스가 우리 사이트를 알아보는 열쇠가 API 키입니다. 키를 가진 쪽은 우리 회사 이름으로 그 서비스를 쓸 수 있으므로, 사실상 비밀번호와 같습니다.

키가 노출되면 남이 우리 계정으로 메일이나 문자를 대량 발송하거나, 유료 서비스를 써서 요금이 청구되거나, 고객 정보가 담긴 데이터를 읽어 갈 수 있습니다. API 키는 홈페이지 코드에 적힌 순간부터 관리 대상이라는 점을 기억해야 합니다.

API 키가 노출되는 흔한 경로

키는 해킹보다 실수로 새는 경우가 많습니다. 방문자 브라우저로 내려가는 자바스크립트 코드에 서버용 키를 적어 두거나, 코드 저장소에 설정 파일을 그대로 올리거나, 업체와 메신저로 키를 주고받고 지우지 않는 경우입니다. 웹에서 열리는 위치에 설정 파일이나 백업 파일을 두는 것도 흔한 원인입니다.

API 키 종류별 보관 위치

아래 표는 홈페이지에서 쓰는 API 키를 브라우저에 보여도 되는지 기준으로 나누어 보관 위치를 비교한 것입니다. 서비스마다 안내가 다르므로 각 서비스의 개발자 문서를 함께 확인합니다.

구분	예	보관 위치	함께 할 일
브라우저용 공개 키	지도 표시용 키 등	화면 코드에 들어갈 수 있음	허용 도메인 제한 필수
서버용 비밀 키	결제 승인, 메일·문자 발송 키	서버의 환경설정에만	화면 코드·저장소에 넣지 않음
관리용 키	클라우드·호스팅 관리 키	필요한 사람의 보관함	최소 권한, 쓰지 않으면 삭제

표에서 브라우저용 공개 키도 그냥 두면 안 됩니다. 남이 그 키를 복사해 자기 사이트에서 쓰지 못하도록, 서비스 관리 화면에서 우리 도메인에서만 쓰이게 제한합니다.

공식 문서가 권하는 API 키 관리 원칙

Google Cloud의 API 키 관리 모범 사례 문서는 키마다 사용 범위를 제한하고, 키를 클라이언트 코드나 저장소에 넣지 말고, 쓰지 않는 키는 지우고, 주기적으로 새 키로 교체하라고 안내합니다. 다른 서비스도 대체로 같은 원칙을 권하므로, 아래 체크리스트를 공통 기준으로 써도 좋습니다.

• 키마다 쓸 수 있는 도메인, IP, 기능을 제한했다.
• 서버용 키는 화면 코드와 코드 저장소에 없다.
• 쓰지 않는 키와 테스트용 키를 지웠다.
• 키 목록에 용도, 발급일, 담당자를 적어 두었다.
• 정해진 주기와 담당자 변경 때 키를 교체한다.

체크리스트의 네 번째 항목인 키 목록이 있어야 나머지를 지킬 수 있습니다. 어떤 키가 어디에 쓰이는지 모르면 교체할 때 어느 기능이 멈출지 알 수 없기 때문입니다.

API 키가 노출됐을 때 교체 5단계

키가 노출됐다는 의심이 들면 지우기보다 교체가 먼저입니다. 노출된 위치에서 키를 지워도 이미 복사된 키는 계속 쓸 수 있으므로, 그 키 자체를 못 쓰게 만들어야 합니다.

1. 노출 범위 확인: 어떤 키가 어디에 노출됐는지, 그 키로 무엇을 할 수 있는지 확인합니다.
2. 새 키 발급: 서비스 관리 화면에서 새 키를 만들고, 기존 키와 같은 사용 범위 제한을 겁니다.
3. 사이트에 새 키 적용: 서버 환경설정의 키를 새 키로 바꾸고, 해당 기능이 정상 동작하는지 확인합니다.
4. 옛 키 폐기: 노출된 키를 서비스에서 비활성화하거나 삭제합니다.
5. 사용 기록 확인: 서비스의 사용량과 요금, 발송 기록에 모르는 사용이 없었는지 확인하고 원인을 막습니다.

그림의 세 번째와 네 번째 단계 순서를 바꾸면 그 사이에 기능이 멈춥니다. 다만 키가 악용되고 있는 정황이 보이면 기능이 잠시 멈추더라도 옛 키를 먼저 막는 것이 낫습니다. 키가 코드 저장소에 올라간 경우는 코드 저장소 비밀정보 노출 글에서 따로 다룹니다.

디코랩이 돕는 방식

디코랩은 웹 서비스와 맞춤형 시스템 제작, 운영 중인 사이트의 유지보수를 맡고 있습니다. 원페이지 홈페이지에는 문의 폼과 카카오톡 알림톡 연동이 무료로 포함되며(발송 이용료 별도), 그 밖의 외부 서비스 연동 범위는 상담 후 제안합니다. 제작 범위는 디코랩 서비스 소개에서 확인할 수 있습니다. 운영 중인 사이트의 키 교체가 필요하다면 유지보수 접수 게시판에 비밀글로 요청을 남겨 주세요.

자주 묻는 질문

API 키는 얼마나 자주 바꿔야 하나요?

정해진 하나의 주기보다 서비스별 안내와 회사 사정에 맞게 정합니다. 최소한 노출이 의심될 때, 키를 알던 담당자나 업체가 바뀔 때는 반드시 교체합니다.

키를 메신저로 업체에 보내도 되나요?

가능하면 피하고, 업체가 직접 서비스에 접근할 계정을 받거나 비밀번호 관리자의 공유 기능을 쓰는 것이 낫습니다. 어쩔 수 없이 보냈다면 작업 후 키를 교체합니다.

브라우저 코드에 보이는 지도 키는 괜찮은가요?

지도 표시용 키처럼 브라우저에서 쓰도록 만든 키는 보일 수밖에 없습니다. 대신 서비스 관리 화면에서 우리 도메인에서만 쓰이게 제한해 두어야 합니다.

키 목록은 어디에 어떻게 적나요?

서비스 이름, 키의 용도, 브라우저용인지 서버용인지, 발급일, 걸어 둔 제한, 담당자, 마지막 교체일을 표로 적습니다. 키 값 자체는 표에 적지 말고 서버 환경설정이나 비밀번호 관리자에만 둡니다.

외주 업체가 만든 사이트라 키 위치를 모르면요?

먼저 사이트에 연결된 외부 서비스 목록을 업체에 요청하고, 각 서비스의 관리 화면에서 발급된 키를 확인합니다. 계약이 끝난 업체가 키를 알고 있었다면 이번 기회에 교체하는 것이 좋습니다.

홈페이지에 연결된 API 키 정리가 필요하다면 디코랩 프로젝트 문의로 연결된 서비스 목록을 알려 주세요.