Claude API 키 만료 운영법: 장기 키를 줄이고 교체 사고를 막는 방법

Anthropic은 2026년 7월 8일 Claude Console에서 API key와 Admin API key 생성 시 만료 시간을 설정할 수 있게 했다고 공지했습니다. preset, custom duration, Never 중에서 선택할 수 있고, 7일 이상 남은 키는 만료 전에 생성자에게 이메일 알림이 갑니다. Admin API는 각 키의 expires_at 필드를 보고합니다. 기존 키는 영향을 받지 않습니다.

작아 보이는 업데이트지만 운영팀에는 중요합니다. AI API 키는 대부분 서비스의 핵심 경로에 붙습니다. 백엔드 Lambda, 크론잡, 사내 도구, 평가 파이프라인, 고객지원 봇, RAG 인덱서 등 여러 곳에 흩어져 있습니다. 키 하나가 새면 비용 폭탄이 나고, 키 하나가 만료되면 서비스가 멈춥니다.

왜 키 만료 기능이 중요한가

그동안 많은 팀이 AI API 키를 사실상 영구 토큰처럼 써왔습니다. 처음 만든 키를 환경변수에 넣고, Vercel이나 GitHub Actions나 Kubernetes secret에 복사하고, 몇 달 뒤 어디에 쓰는지 잊어버립니다. 문제는 사고가 나기 전까지 티가 안 난다는 점입니다.

장기 키의 위험은 네 가지입니다.

퇴사자나 외주 개발자가 만든 키가 계속 살아 있다.
테스트 프로젝트에 넣은 키가 공개 저장소나 로그에 남는다.
어떤 키가 어떤 서비스에서 쓰이는지 추적이 안 된다.
교체하려고 해도 장애가 날까 봐 미루게 된다.

만료 시간을 설정할 수 있으면 키를 "영구 비밀값"이 아니라 "수명 있는 운영 자산"으로 관리할 수 있습니다.

키 수명을 어떻게 나눌까

모든 키에 같은 만료 기간을 주면 운영이 불편합니다. 용도별로 수명을 다르게 잡아야 합니다.

개발자 로컬 키는 짧게 잡는 편이 좋습니다. 7일 또는 14일이면 충분합니다. 로컬 키는 노트북, 셸 히스토리, 임시 스크립트, IDE 플러그인에 노출될 가능성이 큽니다. 만료가 빠를수록 유출 피해 범위가 줄어듭니다.

CI/CD 키는 30일 또는 60일 정도가 현실적입니다. 너무 짧으면 배포 파이프라인이 자주 멈추고, 너무 길면 관리가 느슨해집니다. 교체 자동화가 되어 있다면 더 짧게 가져갈 수 있습니다.

프로덕션 런타임 키는 60일 또는 90일로 시작하는 것을 추천합니다. 단, 무중단 교체 절차가 먼저 있어야 합니다. 프로덕션 키에 만료만 걸어두고 교체 프로세스가 없으면 만료 당일 장애가 납니다.

일회성 분석, 벤치마크, 외주 테스트용 키는 1일~7일이면 충분합니다. 이 범주는 Never를 쓰면 안 됩니다.

expires_at을 운영 지표로 써야 한다

Admin API가 expires_at을 제공한다는 점은 중요합니다. 콘솔에서 사람이 눈으로 보는 수준을 넘어, 키 만료를 모니터링할 수 있기 때문입니다.

실무에서는 매일 한 번 다음 항목을 점검하는 크론을 두는 것이 좋습니다.

7일 이내 만료되는 키 목록
소유자 또는 생성자가 없는 키
이름 규칙을 따르지 않는 키
Never로 설정된 키
최근 30일간 사용 기록이 없는 키

이 중 7일 이내 만료 키는 Slack, Discord, 이메일로 알림을 보내야 합니다. Never 키는 예외 승인 목록에 없으면 교체 대상으로 잡아야 합니다.

키 이름도 중요합니다. "test", "prod", "new key" 같은 이름은 사고를 부릅니다. 최소한 다음 형식을 권장합니다.

서비스명-환경-용도-소유자

예를 들면 aibase-prod-posting-cron-blico, support-staging-rag-api-mina처럼 적습니다. 키 이름만 봐도 어디에 쓰는지 알 수 있어야 합니다.

무중단 교체 절차

키 만료 정책의 핵심은 만료가 아니라 교체입니다. 교체가 자동화되어 있지 않으면 만료 기능은 장애 예약 기능이 됩니다.

안전한 절차는 다음과 같습니다.

새 키를 만든다.
Secret Manager나 배포 환경에 새 키를 추가한다.
애플리케이션이 새 키를 읽도록 배포한다.
헬스체크와 실제 API 호출을 확인한다.
기존 키를 비활성화하거나 삭제한다.
롤백할 수 있도록 변경 이력을 남긴다.

가능하면 키를 하나의 환경변수 이름에 덮어쓰는 방식보다, 임시로 OLD_KEY와 NEW_KEY를 함께 두고 전환하는 방식을 쓰세요. 장애가 나면 빠르게 되돌릴 수 있습니다.

Never 옵션을 언제 써도 되는가

Never는 편하지만 기본값이 되어서는 안 됩니다. 정말 예외적인 경우에만 쓰는 편이 좋습니다.

예외 후보는 다음 정도입니다.

폐쇄망 또는 별도 보안 경계 안에서 돌아가는 장기 시스템
키 교체가 즉시 장애로 이어지고 아직 개선 일정이 잡힌 레거시 서비스
별도 외부 비밀관리 시스템에서 수명을 이미 관리하는 경우

그래도 Never 키에는 반드시 소유자, 사용처, 다음 리뷰 날짜를 붙여야 합니다. 리뷰 날짜가 없는 Never 키는 사실상 방치된 키입니다.

팀 정책으로 바꿔야 할 것

첫째, 새 키 생성 시 만료 기간을 필수로 정하세요. 생성자가 "왜 Never가 필요한지" 설명하지 못하면 Never를 허용하지 않는 것이 안전합니다.

둘째, 로컬 개발 키와 프로덕션 키를 분리하세요. 개발자가 로컬에서 쓰는 키가 프로덕션 권한을 가지면 안 됩니다.

셋째, 키 교체를 릴리즈 작업으로 취급하세요. 단순 설정 변경이 아니라 장애 가능성이 있는 운영 작업입니다. 체크리스트와 검증 로그가 필요합니다.

넷째, 만료 알림을 사람 한 명에게만 보내지 마세요. 키 생성자가 휴가 중이거나 퇴사했을 수 있습니다. 서비스 오너 그룹에도 보내야 합니다.

오늘 적용할 체크리스트

Claude Console의 모든 API key와 Admin API key 목록을 확인한다.
Never 키를 찾아 사용처, 소유자, 리뷰 날짜를 기록한다.
새 키 이름 규칙을 서비스명-환경-용도-소유자 형식으로 정한다.
개발자 로컬 키는 7~~14일, CI 키는 30~~60일, 프로덕션 키는 60~90일로 시작한다.
expires_at을 읽어 7일 이내 만료 키를 알리는 크론을 만든다.
키 교체 절차를 runbook으로 문서화하고 실제로 한 번 리허설한다.

출처: Anthropic Claude Platform release notes, Claude Console authentication documentation.