API Key 인증 설계 — 발급, 로테이션, 권한 범위

구독결제 API는 매출과 직결되는 데이터를 다루기 때문에, API Key 하나를 어떻게 설계하느냐가 보안 사고의 크기를 좌우합니다. OAuth 같은 복잡한 체계 없이도, 몇 가지 원칙만 지키면 충분히 안전한 API Key 인증을 만들 수 있습니다.

키 형식 — 접두사로 환경을 구분한다

Stripe가 대중화시킨 방식처럼, 키 앞에 환경을 나타내는 접두사를 붙이면 실무 사고를 크게 줄일 수 있습니다.

sk_live_51H... (프로덕션)
sk_test_51H... (테스트)

접두사가 없으면 개발자가 테스트 키를 프로덕션 환경변수에 잘못 넣거나, 반대로 라이브 키를 로컬에서 실험용으로 쓰다가 실제 카드에 청구되는 사고가 납니다. 접두사만으로도 코드 리뷰나 로그에서 "이거 라이브 키 아니야?"라는 즉각적인 알림이 가능해집니다.

저장은 해시로, 원문은 발급 시 한 번만 노출

API Key는 비밀번호와 동일하게 취급해야 합니다. DB에는 원문을 저장하지 않고 해시(SHA-256 등)만 저장하며, 원문은 발급 화면에서 딱 한 번만 보여주고 이후로는 다시 조회할 수 없게 합니다. 키를 분실했다면 "재발급"만 가능하고 "다시 보기"는 불가능해야 안전합니다.

권한 범위(Scope)는 최소한만

작은 팀에서는 "읽기 전용 키"와 "전체 권한 키" 두 단계만으로도 실무 사고의 상당수를 막을 수 있습니다.

• 읽기 전용 키: 대시보드 임베드, 리포팅 도구 연동용
• 전체 권한 키: 서버 사이드에서 구독 생성/취소 등 쓰기 작업용

권한을 세분화할수록 안전해지지만, 세분화 자체가 관리 복잡도를 늘리므로 초기에는 두 단계로 시작해 실제 요청이 있을 때 세분화하는 편이 낫습니다.

로테이션은 "즉시 폐기"가 아니라 "유예 기간"을 둔다

키가 유출된 게 확실하지 않은 일상적인 로테이션 상황(정기 교체, 팀원 퇴사)에서는 새 키를 발급한 직후 기존 키를 바로 무효화하지 않는 것이 좋습니다. 배포 중인 서버가 여러 대라면 환경변수 교체가 동시에 끝나지 않기 때문입니다. 슈퍼빌링은 새 키 발급 후 기존 키를 24시간 동안 함께 유효하게 두고, 이후 자동 폐기합니다. 단, 유출이 확실한 경우는 유예 없이 즉시 폐기하는 별도 버튼을 제공해야 합니다.

Rate Limit은 키 단위로

IP 단위 rate limit은 여러 고객사가 같은 게이트웨이/프록시 뒤에 있을 때 서로에게 영향을 줄 수 있습니다. API Key 단위로 제한을 걸어야 한 고객사의 트래픽 폭주가 다른 고객사에게 전가되지 않습니다.

API Key로 인증을 재사용해 AI 에이전트에게 결제 연동 자체를 맡기는 방법은 AI 에이전트에게 결제 연동을 맡기는 법 (Remote MCP)에서 다룹니다. 전체 연동 가이드는 구독결제 연동 완전 가이드를 참고하세요.