API Key

An application programming interface key (API key) is a unique identifier used to authenticate and authorize a user, developer, or calling program to an API.

— IETF Web API 보안 설계 지침

서버 간 통신을 가장 쉽고 편하게 뚫어주지만, 실수로 깃허브 퍼블릭 레포에 소스 코드를 밀어 넣는 순간 전 세계 스캐너 봇들이 3초 만에 감지해서 내 지갑을 거덜 내게 만드는 아킬레스건. 아차 하고 커밋한 OpenAI API Key 때문에 다음 날 아침 5,000달러 결제 문자를 받고 눈물로 하루를 시작하게 만드는 주범이다.(...)

1. 개요

애플리케이션이 다른 애플리케이션이나 외부 서비스(API)를 호출할 때, 자신을 식별하고 권한을 획득하기 위해 전송하는 고유한 암호화 문자열. 복잡한 핸드셰이크를 요구하는 OAuth나 상태를 유지해야 하는 세션 인증과 달리, 요청에 이 고유 열쇠 문자열 하나만 실어서 보내면 즉시 검증이 완료되는 극도로 가볍고 편리한 인증 패턴이다.

2. 서버 간 통신(M2M)의 친절한 열쇠

API Key는 브라우저를 띄워 사용자가 직접 아이디와 패스워드를 입력하는 대화형 로그인이 불가능한 시스템 대 시스템(Machine-to-Machine) 통신에서 가장 빛을 발한다. 공공데이터 포털의 날씨 정보나 구글 지도를 내 홈페이지에 이식하고 싶을 때, 해당 서비스 제공업체에 신청하여 긴 난수 문자열(API Key)을 발급받는다. 이후 HTTP 요청 헤더(Authorization: Apikey <KEY>)나 쿼리 파라미터(?apikey=<KEY>)에 이를 실어 보낸다. 서버는 요청이 오면 단순히 이 키가 유효한 목록에 있는지만 대조하여 통과 여부를 정하고, 호출 횟수를 집계해 트래픽 사용량 제어(Rate Limiting)와 과금을 수행한다.1

3. GitHub 노출 대참사와 보안 우수 사례

API Key의 가장 치명적인 치명타는 물리적 보안 노출이다. 초보 개발자들이 하드코딩된 API Key를 담은 소스 코드를 그대로 GitHub 퍼블릭 저장소에 커밋하는 실수를 심심치 않게 저지른다. 전 세계의 해커들은 깃허브 커밋 로그를 실시간으로 긁어가는 스캐너 봇(Scanner Bot)을 24시간 풀가동하고 있기 때문에, 푸시 후 채 5초도 지나지 않아 키가 전 세계 해커들에게 수집된다. 해커들은 훔친 키로 AWS 가상 머신 수백 대를 켜서 암호화폐 채굴을 돌리거나 대형 언어 모델(LLM) API를 난사해 크레딧 폭탄을 안겨준다. 이를 방지하기 위해 키는 반드시 .env 같은 환경 변수 파일에 보관하고 깃 제외 목록(.gitignore)에 등록해야 하며, 도메인 제한이나 IP 화이트리스트, 주기적인 키 순환(Rotation) 정책을 강력히 동원해야 한다.

4. 관련 밈 및 드립

4.1. AWS 크레딧 폭탄과 메일 한 통의 기적

깃허브에 API Key가 털려 하루아침에 수천만 원의 과금 청구서를 받고 기절하기 일보 직전인 주니어 개발자들이 구글에 'AWS 과금 감면받는 법'을 눈물겹게 검색하는 슬픈 해프닝. 실제로 AWS나 OpenAI 등의 빅테크 기업 고객센터에 '제가 멍청한 주니어라 코딩 공부 중 실수를 저질렀습니다, 제발 한 번만 살려주세요'라며 진심 어린 영문 참회 메일을 보내면, 일생에 단 한 번 기적적으로 청구 요금을 100% 감면해 준다는 '면죄부' 메일 인증 짤방이 커뮤니티의 전설적인 바이블로 공유되곤 한다.(...)

4.2. 비밀번호는 .env에 양보하세요

소스 코드 내부에 암호와 API 키를 직접 써두지 말라는 시니어들의 잔소리가 귀에 딱지가 앉도록 들려오는 환경에서 나온 드립. 심지어 프론트엔드 리액트 코드 안에 REACT_APP_ 접두사를 붙여 API 키를 환경 변수로 넣어 숨겼다고 안심하지만, 리액트 빌드 결과물(JavaScript)을 브라우저 개발자 도구로 까보면 그 비밀 키가 생문자열로 고스란히 노출된다는 사실을 뒤늦게 깨닫고 공포에 떠는 프론트 주니어들의 웃픈 오해를 꼬집는 밈이다.

5. 여담

  • Symmetric Key와의 차이: API Key는 기본적으로 '대칭 키(Symmetric Key)' 역할을 한다. 발급받은 클라이언트와 검증하는 서버 둘 다 동일한 키 문자열을 그대로 알고 있어야 하기 때문이다. 따라서 통신 중간에 패킷을 가로채거나 가짜 HTTPS 인증서 공격(MITM)에 취약해 반드시 SSL/TLS 암호화 통신 위에서만 안전하게 사용되어야 한다.
  • REST API 설계의 악당: REST API의 무상태성 설계 원칙을 지키기 위해서는 매 요청마다 API Key를 대조해야 한다. 하지만 데이터베이스에서 매 요청마다 API Key가 활성화 상태인지 SQL로 검색하면 엄청난 DB 부하가 발생하므로, 실무에서는 캐시 서버에 유효 키 목록을 올려두고 1차 필터링을 거치게 설계한다.
  • OAuth와의 협업: 어떤 대형 플랫폼(예: 카카오, 네이버)들은 기본적인 서비스 식별에는 단순한 API Key(클라이언트 ID)를 쓰고, 실제 사용자 개인정보가 얽힌 영역에 들어가서 비로소 보안성이 월등히 높고 발급 절차가 복잡한 OAuth 토큰을 요구하는 투트랙 보안 체제를 사용한다.

6. 관련 문서

각주

  1. API Key의 다른 명칭으로는 개발자 키(Developer Key), 애플리케이션 ID(Application ID), 클라이언트 토큰(Client Token) 등이 도구에 따라 혼용되어 불린다. ↩

이 문서를 가리키는 문서