API 키 관리

API 키 보안이 중요한 이유

실제 사례

위협 모델

API 키 유형별 보안 요구사항

환경 변수 사용

기본 사용법

1. .env 파일 생성

# 프로젝트 루트에 .env 파일 생성
# NEVER commit this file!

# Anthropic (Claude)
ANTHROPIC_API_KEY=sk-ant-api03-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# OpenAI (GPT, o1)
OPENAI_API_KEY=sk-proj-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Google (Gemini)
GOOGLE_API_KEY=AIzaSyxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Ollama (로컬 LLM)
OLLAMA_HOST=http://localhost:11434

# 앱 설정
APP_ENV=development
LOG_LEVEL=debug

2. .gitignore 설정 (필수!)

# .gitignore - 절대 커밋되지 않도록

# 환경 변수 파일
.env
.env.local
.env.*.local
.env.development
.env.production

# 키 파일
*.key
*.pem
secrets.json
credentials.json

# macOS
.DS_Store

# 에디터
.vscode/settings.json
.idea/

3. .env.example 작성 (권장)

# .env.example - Git에 커밋하여 팀과 공유

# OpenAI API Key (https://console.anthropic.com/)
ANTHROPIC_API_KEY=sk-ant-api03-your-key-here

# OpenAI API Key (https://platform.openai.com/api-keys)
OPENAI_API_KEY=sk-proj-your-key-here

# Google API Key (optional)
GOOGLE_API_KEY=

# Ollama Host (default: http://localhost:11434)
OLLAMA_HOST=http://localhost:11434

Python에서 사용

# 1. python-dotenv 설치
pip install python-dotenv

# 2. 코드에서 사용
from dotenv import load_dotenv
import os

# .env 로드
load_dotenv()

# 환경 변수 읽기
api_key = os.getenv('ANTHROPIC_API_KEY')

# 기본값 제공
host = os.getenv('OLLAMA_HOST', 'http://localhost:11434')

# 필수 변수 검증
if not api_key:
    raise ValueError("ANTHROPIC_API_KEY가 설정되지 않았습니다!")

# 3. Anthropic 클라이언트
import anthropic

client = anthropic.Anthropic(
    api_key=os.getenv('ANTHROPIC_API_KEY')
)

환경별 설정 (.env.development, .env.production)

# .env.development
ANTHROPIC_API_KEY=sk-ant-api03-dev-key
APP_ENV=development
LOG_LEVEL=debug

# .env.production
ANTHROPIC_API_KEY=sk-ant-api03-prod-key
APP_ENV=production
LOG_LEVEL=info

# Python 코드
import os
from dotenv import load_dotenv

# 환경에 따라 .env 파일 선택
env = os.getenv('APP_ENV', 'development')
load_dotenv(f'.env.{env}')

Node.js/TypeScript에서 사용

// 1. dotenv 설치
npm install dotenv

// 2. 앱 시작 시 로드 (server.ts 또는 index.ts)
import 'dotenv/config';  // ES6
// 또는
require('dotenv').config();  // CommonJS

// 3. 환경 변수 사용
const apiKey = process.env.ANTHROPIC_API_KEY;

// 4. TypeScript 타입 정의
// env.d.ts
declare namespace NodeJS {
  interface ProcessEnv {
    ANTHROPIC_API_KEY: string;
    OPENAI_API_KEY: string;
    OLLAMA_HOST?: string;
    APP_ENV: 'development' | 'production';
  }
}

// 5. 검증 함수
function validateEnv() {
  const required = ['ANTHROPIC_API_KEY', 'OPENAI_API_KEY'];
  for (const key of required) {
    if (!process.env[key]) {
      throw new Error(`Missing required env: ${key}`);
    }
  }
}

validateEnv();

쉘 환경 변수 설정

# ~/.zshrc 또는 ~/.bashrc

# API 키 설정 (개발 환경에만!)
export ANTHROPIC_API_KEY="sk-ant-api03-..."
export OPENAI_API_KEY="sk-proj-..."

# 또는 별도 파일로 분리 (더 안전)
# ~/.api_keys (권한: 600)
export ANTHROPIC_API_KEY="sk-ant-api03-..."
export OPENAI_API_KEY="sk-proj-..."

# ~/.zshrc에서 로드
if [ -f ~/.api_keys ]; then
  source ~/.api_keys
fi

# 권한 설정 (본인만 읽기)
chmod 600 ~/.api_keys

시크릿 관리자 사용

1Password (개인/소규모 팀)

1. 1Password CLI 설치

# macOS
brew install --cask 1password-cli

# Ubuntu/Debian
curl -sS https://downloads.1password.com/linux/keys/1password.asc | \
  sudo gpg --dearmor --output /usr/share/keyrings/1password-archive-keyring.gpg
echo 'deb [arch=amd64 signed-by=/usr/share/keyrings/1password-archive-keyring.gpg] https://downloads.1password.com/linux/debian/amd64 stable main' | \
  sudo tee /etc/apt/sources.list.d/1password.list
sudo apt update && sudo apt install 1password-cli

# 로그인
eval $(op signin)

2. API 키 저장

# 대화형으로 저장
op item create --category="API Credential" \
  --title="OpenAI API Key" \
  --vault="Development" \
  "username=ANTHROPIC_API_KEY" \
  "credential=sk-ant-api03-..."

3. 코드에서 사용

# Python
import subprocess
import json

def get_secret(item_name, field='credential'):
    result = subprocess.run(
        ['op', 'item', 'get', item_name, '--fields', field, '--format', 'json'],
        capture_output=True,
        text=True
    )
    return json.loads(result.stdout)['value']

api_key = get_secret('OpenAI API Key')

// Node.js
import { execSync } from 'child_process';

function getSecret(itemName: string, field = 'credential'): string {
  const output = execSync(
    `op item get "${itemName}" --fields ${field}`,
    { encoding: 'utf-8' }
  );
  return output.trim();
}

const apiKey = getSecret('OpenAI API Key');

Bitwarden (오픈소스 대안)

# CLI 설치
# macOS
brew install bitwarden-cli

# Ubuntu/Debian
sudo snap install bw

# 로그인
bw login
export BW_SESSION="$(bw unlock --raw)"

# API 키 저장
bw create item --organizationid null \
  --name "OpenAI API Key" \
  --username "ANTHROPIC_API_KEY" \
  --password "sk-ant-api03-..."

# 키 가져오기
bw get password "OpenAI API Key"

AWS Secrets Manager (프로덕션)

# AWS CLI 설치
# macOS
brew install awscli

# Ubuntu/Debian
sudo apt install awscli

# 인증 설정
aws configure

# 시크릿 생성
aws secretsmanager create-secret \
  --name prod/anthropic/api-key \
  --secret-string "sk-ant-api03-..."

# 시크릿 읽기
aws secretsmanager get-secret-value \
  --secret-id prod/anthropic/api-key \
  --query SecretString \
  --output text

Python 코드에서 사용

import boto3
from botocore.exceptions import ClientError

def get_secret(secret_name, region_name="us-west-2"):
    session = boto3.session.Session()
    client = session.client(
        service_name='secretsmanager',
        region_name=region_name
    )

    try:
        response = client.get_secret_value(SecretId=secret_name)
        return response['SecretString']
    except ClientError as e:
        raise Exception(f"Failed to retrieve secret: {e}")

# 사용
api_key = get_secret('prod/anthropic/api-key')

Google Secret Manager

# gcloud CLI 설치
# macOS
brew install --cask google-cloud-sdk

# Ubuntu/Debian
sudo snap install google-cloud-sdk --classic

# 인증
gcloud auth login
gcloud config set project YOUR_PROJECT_ID

# 시크릿 생성
echo -n "sk-ant-api03-..." | \
  gcloud secrets create anthropic-api-key \
    --data-file=- \
    --replication-policy="automatic"

# 시크릿 읽기
gcloud secrets versions access latest --secret="anthropic-api-key"

Python 코드

from google.cloud import secretmanager

def get_secret(project_id, secret_id, version_id="latest"):
    client = secretmanager.SecretManagerServiceClient()
    name = f"projects/{project_id}/secrets/{secret_id}/versions/{version_id}"
    response = client.access_secret_version(request={"name": name})
    return response.payload.data.decode("UTF-8")

api_key = get_secret("my-project", "anthropic-api-key")

HashiCorp Vault (엔터프라이즈)

# Vault 설치
# macOS
brew tap hashicorp/tap
brew install hashicorp/tap/vault

# 개발 서버 시작
vault server -dev

# 환경 변수 설정
export VAULT_ADDR='http://127.0.0.1:8200'
export VAULT_TOKEN="root"  # 개발 전용

# 시크릿 저장
vault kv put secret/anthropic api_key="sk-ant-api03-..."

# 시크릿 읽기
vault kv get -field=api_key secret/anthropic

# Python
import hvac

client = hvac.Client(url='http://127.0.0.1:8200', token='root')
secret = client.secrets.kv.v2.read_secret_version(path='anthropic')
api_key = secret['data']['data']['api_key']

Git 커밋 방지

완벽한 .gitignore

# ========== 환경 변수 ==========
.env
.env.local
.env.*.local
.env.development
.env.production
.env.test

# ========== API 키 파일 ==========
*.key
*.pem
*.p12
*.pfx
secrets.json
credentials.json
service-account.json

# ========== 설정 파일 ==========
config/secrets.yml
config/credentials.yml
.secrets/
.credentials/

# ========== 데이터베이스 ==========
*.db
*.sqlite
*.sqlite3

# ========== 로그 ==========
*.log
logs/

# ========== OS ==========
.DS_Store
Thumbs.db

# ========== 에디터 ==========
.vscode/settings.json
.idea/workspace.xml
*.swp
*.swo

# ========== 의존성 ==========
node_modules/
venv/
__pycache__/
*.pyc

Pre-commit 훅 (자동 검증)

# .git/hooks/pre-commit
#!/bin/bash

# API 키 패턴 정의
PATTERNS=(
  "sk-ant-"           # Anthropic
  "sk-proj-"          # OpenAI (project)
  "sk-[a-zA-Z0-9]{48}" # OpenAI (legacy)
  "AIzaSy"            # Google
  "AKIA[0-9A-Z]{16}"   # AWS Access Key
  "ghp_[a-zA-Z0-9]{36}" # GitHub Personal Access Token
)

# 스테이징된 파일 검사
for pattern in "${PATTERNS[@]}"; do
  if git diff --cached | grep -E "$pattern" >/dev/null; then
    echo "❌ ERROR: API 키가 감지되었습니다!"
    echo "   패턴: $pattern"
    echo ""
    echo "   다음 명령어로 변경사항 취소:"
    echo "   git reset HEAD <file>"
    exit 1
  fi
done

# .env 파일 검사
if git diff --cached --name-only | grep -E '^\.env' >/dev/null; then
  echo "❌ ERROR: .env 파일을 커밋하려고 합니다!"
  echo "   .env 파일은 절대 커밋하지 마세요."
  exit 1
fi

echo "✅ Pre-commit 검증 통과"
exit 0

# 실행 권한 부여
chmod +x .git/hooks/pre-commit

Gitleaks (자동 스캔 도구)

# 설치
# macOS
brew install gitleaks

# Ubuntu/Debian
wget https://github.com/gitleaks/gitleaks/releases/download/v8.18.1/gitleaks_8.18.1_linux_x64.tar.gz
tar -xzf gitleaks_8.18.1_linux_x64.tar.gz
sudo mv gitleaks /usr/local/bin/

# 현재 브랜치 스캔
gitleaks detect --source . --verbose

# Git 히스토리 전체 스캔
gitleaks detect --source . --log-opts "--all"

# Pre-commit 훅으로 통합
gitleaks protect --staged --verbose

.gitleaks.toml 설정

title = "Custom Gitleaks Config"

[[rules]]
id = "anthropic-api-key"
description = "OpenAI API Key"
regex = '''sk-ant-api03-[A-Za-z0-9_-]{95}'''

[[rules]]
id = "openai-api-key"
description = "OpenAI API Key"
regex = '''sk-proj-[A-Za-z0-9_-]{43,}'''

[[rules]]
id = "google-api-key"
description = "Google API Key"
regex = '''AIzaSy[A-Za-z0-9_-]{33}'''

[allowlist]
paths = [
  '''.env.example''',
  '''docs/'''
]

GitHub Secret Scanning

# Private 저장소에서도 활성화 (Settings → Security)
# 1. Settings → Code security and analysis
# 2. Secret scanning → Enable
# 3. Push protection → Enable (권장)

프로덕션 베스트 프랙티스

백엔드 프록시 패턴

Node.js 프록시 서버 예제

// server.js
import express from 'express';
import Anthropic from '@anthropic-ai/sdk';

const app = express();
app.use(express.json());

// API 키는 서버 환경 변수에만 존재
const client = new Anthropic({
  apiKey: process.env.ANTHROPIC_API_KEY,
});

// 프록시 엔드포인트
app.post('/api/chat', async (req, res) => {
  try {
    // 1. 사용자 인증 검증
    const userId = req.headers['x-user-id'];
    if (!userId) return res.status(401).json({ error: 'Unauthorized' });

    // 2. Rate limiting (사용자당)
    const rateLimit = await checkRateLimit(userId);
    if (!rateLimit.allowed) {
      return res.status(429).json({ error: 'Rate limit exceeded' });
    }

    // 3. Claude API 호출
    const message = await client.messages.create({
      model: 'claude-',
      max_tokens: 4096,
      messages: req.body.messages,
    });

    // 4. 사용량 로깅
    await logUsage(userId, message.usage);

    res.json(message);
  } catch (error) {
    console.error('Proxy error:', error);
    res.status(500).json({ error: 'Internal server error' });
  }
});

app.listen(3000);

Python Flask 프록시

from flask import Flask, request, jsonify
from anthropic import Anthropic
import os

app = Flask(__name__)
client = Anthropic(api_key=os.getenv('ANTHROPIC_API_KEY'))

@app.route('/api/chat', methods=['POST'])
def chat_proxy():
    # 인증 검증
    user_id = request.headers.get('X-User-Id')
    if not user_id:
        return jsonify({'error': 'Unauthorized'}), 401

    # Rate limiting
    if not check_rate_limit(user_id):
        return jsonify({'error': 'Rate limit exceeded'}), 429

    # Claude API 호출
    message = client.messages.create(
        model='claude-',
        max_tokens=4096,
        messages=request.json['messages']
    )

    # 사용량 로깅
    log_usage(user_id, message.usage)

    return jsonify(message.model_dump())

if __name__ == '__main__':
    app.run(port=5000)

키 로테이션

로테이션 전략

AWS Secrets Manager 자동 로테이션

# Lambda 함수로 자동 로테이션 설정
aws secretsmanager rotate-secret \
  --secret-id prod/anthropic/api-key \
  --rotation-lambda-arn arn:aws:lambda:us-west-2:123456789012:function:RotateAnthropicKey \
  --rotation-rules AutomaticallyAfterDays=90

수동 로테이션 스크립트

#!/bin/bash
# rotate-api-key.sh

# 1. 새 API 키 생성 (Anthropic Console에서)
echo "1. https://console.anthropic.com/ 에서 새 API 키 생성"
read -p "새 API 키: " NEW_KEY

# 2. AWS Secrets Manager 업데이트
aws secretsmanager update-secret \
  --secret-id prod/anthropic/api-key \
  --secret-string "$NEW_KEY"

# 3. 앱 재시작 (새 키 로드)
kubectl rollout restart deployment/api-server

# 4. 구 키가 더 이상 사용되지 않는지 모니터링 (1주일)
echo "✅ 새 키 배포 완료"
echo "⏰ 1주일 후 구 키를 Anthropic Console에서 삭제하세요"

사용량 모니터링

# Python: 모든 API 호출 로깅
import logging
import json
from datetime import datetime

def log_api_usage(user_id, model, usage):
    log_entry = {
        "timestamp": datetime.utcnow().isoformat(),
        "user_id": user_id,
        "model": model,
        "input_tokens": usage.input_tokens,
        "output_tokens": usage.output_tokens,
        "cost_usd": calculate_cost(model, usage),
    }
    logging.info(json.dumps(log_entry))

def calculate_cost(model, usage):
    # Claude Sonnet (균형) 가격 (2024년 기준)
    if model == 'claude-':
        input_cost = usage.input_tokens / 1_000_000 * 3.00
        output_cost = usage.output_tokens / 1_000_000 * 15.00
        return input_cost + output_cost
    # 다른 모델...

키 유출 시 대응

즉시 조치 체크리스트

Git 히스토리에서 키 제거

방법 1: git filter-repo (권장)

# git-filter-repo 설치
# macOS
brew install git-filter-repo

# Ubuntu/Debian
pip3 install git-filter-repo

# 특정 문자열 히스토리에서 제거
git filter-repo --replace-text <(echo "sk-ant-api03-OLD_KEY==>***REMOVED***")

# 특정 파일 히스토리에서 완전 삭제
git filter-repo --path .env --invert-paths

# Force push (주의: 협업 시 팀원과 조율 필요)
git push origin --force --all

방법 2: BFG Repo-Cleaner

# BFG 다운로드
# https://rtyley.github.io/bfg-repo-cleaner/

# 저장소 미러 클론
git clone --mirror https://github.com/user/repo.git

# 문자열 제거
java -jar bfg.jar --replace-text replacements.txt repo.git

# replacements.txt 내용:
# sk-ant-api03-OLD_KEY==>***REMOVED***

# 정리 및 푸시
cd repo.git
git reflog expire --expire=now --all
git gc --prune=now --aggressive
git push

재발 방지

# 1. Pre-commit 훅 설치 (위 참조)
chmod +x .git/hooks/pre-commit

# 2. Gitleaks CI 추가 (.github/workflows/gitleaks.yml)
name: gitleaks
on: [push, pull_request]
jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0
      - uses: gitleaks/gitleaks-action@v2

# 3. GitHub Branch Protection
# Settings → Branches → Add rule
# ✅ Require status checks to pass (gitleaks)

# 4. 팀 교육
# - API 키 보안 중요성 교육
# - .env.example 사용법
# - 시크릿 관리자 사용법

종합 베스트 프랙티스

반드시 해야 할 것 ✅

• 환경 변수 사용: .env 파일 또는 시크릿 관리자
• .gitignore 설정: .env, *.key 등 즉시 추가
• Pre-commit 훅: 커밋 전 자동 검증
• 백엔드 프록시: 클라이언트에 키 노출 금지
• 키 분리: 개발/테스트/프로덕션 키 분리
• 최소 권한: 필요한 권한만 부여
• 정기 로테이션: 90일마다 키 갱신
• 사용량 모니터링: 이상 패턴 감지
• Rate limiting: 사용자당 요청 제한
• 로깅: 모든 API 호출 로그 (키 제외)

절대 하지 말아야 할 것 ❌

• Git 커밋: API 키를 절대 커밋하지 않기
• 하드코딩: 소스 코드에 직접 작성
• 클라이언트 노출: 브라우저에서 접근 가능하게
• 로그 출력: console.log()에 키 포함
• 이메일/슬랙: 평문으로 공유
• 스크린샷: 키가 보이는 화면 캡처
• 공개 저장소: .env를 public repo에 포함
• 단일 키: 모든 환경에서 같은 키 사용
• 무제한 권한: 필요 이상의 권한 부여
• 방치: 키를 수년간 로테이션 없이 사용

보안 체크리스트

도구 비교

다음 단계

핵심 정리

• API 키 관리의 핵심 개념과 흐름을 정리합니다.
• API 키 보안이 중요한 이유를 단계별로 이해합니다.
• 실전 적용 시 기준과 주의점을 확인합니다.

실무 팁

• 입력/출력 예시를 고정해 재현성을 확보하세요.
• API 키 관리 범위를 작게 잡고 단계적으로 확장하세요.
• API 키 보안이 중요한 이유 조건을 문서화해 대응 시간을 줄이세요.