API 키 관리의 현실 — .env부터 시크릿 매니저까지

API 키는 어디에 저장하는가

개발자라면 API 키를 다루는 게 일상이다. OpenAI, Supabase, Cloudflare, AWS — 서비스마다 키가 있다. 이 키들을 어디에 저장하고 있는가?

현실적인 순서:

1. 소스 코드에 하드코딩 — 최악. GitHub에 올라가면 끝
2. 메모장/노션에 복붙 — 흔하지만 위험
3. .env 파일 — 기본적인 방법
4. 시크릿 매니저 — 제대로 된 방법

대부분이 2~3번에 머물러 있다. 이것의 리스크와 개선 방법을 정리한다.

.env 파일 — 기본이자 한계

# .env
OPENAI_API_KEY=sk-proj-xxxxxxxxxxxx
SUPABASE_URL=https://xxx.supabase.co
SUPABASE_KEY=eyJhbGciOiJIUzI1NiIs...
CLOUDFLARE_API_TOKEN=xxxxxxxxxxxx

장점

• 간단하다
• 대부분의 프레임워크가 지원한다 (dotenv, Vite, Next.js)
• .gitignore에 추가하면 Git에 올라가지 않는다

한계

• 평문 저장: 파일을 열면 키가 보인다
• 공유 어려움: 팀원에게 전달할 때 슬랙/이메일로 보내기도 함
• 버전 관리 안 됨: 키를 로테이션하면 어디서 쓰이는지 추적이 안 됨
• 로컬 전용: 개발 환경에서만 사용, 프로덕션은 별도 관리 필요

.env 파일 최소 보안 수칙

.env를 쓰더라도 이것만은 지키자.

1. .gitignore 필수

.env
.env.local
.env.production

.env.example을 만들어 필요한 변수 목록만 커밋한다:

# .env.example
OPENAI_API_KEY=
SUPABASE_URL=
SUPABASE_KEY=

2. 클라이언트 노출 주의

프론트엔드에서 접근 가능한 환경 변수는 브라우저에 노출된다.

// Next.js: NEXT_PUBLIC_ 접두사가 붙으면 클라이언트에 노출
NEXT_PUBLIC_API_URL=https://api.example.com  // OK (공개 가능한 정보)
NEXT_PUBLIC_SECRET_KEY=xxx                    // 절대 안 됨!

비밀 키는 반드시 서버 사이드에서만 사용해야 한다.

3. 키 별로 권한 최소화

가능하면 전체 권한(admin)이 아닌, 필요한 권한만 가진 키를 발급한다.

• Supabase: anon 키 (RLS로 보호) vs service_role 키 (서버에서만 사용)
• Cloudflare: API 토큰에 특정 Zone만 허용

단계별 보안 향상

레벨 1: .env + .gitignore

• 가장 기본. 개인 프로젝트에서 최소한
• 키가 로컬 파일에 평문으로 존재

레벨 2: 플랫폼 환경 변수

• Vercel, Cloudflare, Railway 등의 환경 변수 설정 사용
• 대시보드에서 관리, 코드에 키가 없음
• 프로덕션과 개발 환경을 분리

# Cloudflare Pages 환경 변수 설정
# 대시보드 → Settings → Environment variables
# Production과 Preview를 별도로 설정

레벨 3: 시크릿 매니저

• AWS Secrets Manager, HashiCorp Vault, 1Password CLI
• 키가 암호화되어 저장됨
• 접근 로그 기록
• 자동 로테이션 가능

# 1Password CLI 예시
op read "op://Development/OpenAI/API Key"

# AWS Secrets Manager
aws secretsmanager get-secret-value --secret-id myapp/openai

레벨 4: 로컬 전용 시크릿 매니저

• KeyBox 같은 도구로 로컬 개발용 키를 암호화 관리
• 마스터 패스워드로 잠금
• 네트워크 연결 불필요

키가 유출되면

1. 즉시 키를 무효화한다. 서비스 대시보드에서 키를 삭제하거나 로테이션
2. 새 키를 발급받아 교체
3. 유출 경로를 파악한다. Git 히스토리, 로그, 슬랙 메시지 등 확인
4. 영향 범위를 확인한다. 유출된 키로 어떤 API가 호출되었는지

GitHub는 공개 저장소에서 시크릿 패턴을 감지하면 자동으로 서비스 제공자에게 알린다 (Secret Scanning). 하지만 이건 사후 대응이다. 예방이 훨씬 중요하다.

정리

개인 프로젝트에서는 .env + .gitignore + 플랫폼 환경 변수가 현실적인 최선이다. 키를 코드에 넣지 않고, 환경별로 분리하고, 권한을 최소화하는 것만으로도 대부분의 사고를 막을 수 있다. 여유가 된다면 시크릿 매니저로 한 단계 올리자.