sam-react-prod/claudedocs/api/[IMPL-2025-11-07] api-key-management.md

API Key 관리 가이드

📋 개요

PHP 백엔드에서 발급하는 API Key의 안전한 관리 및 주기적 갱신 대응 방법

---

🔑 현재 API Key 정보

개발용 API Key:
  키 값: 42Jfwc6EaRQ04GNRmLR5kzJp5UudSOzGGqjmdk1a
  발급일: 2025-11-07
  용도: 개발 환경 고정 키
  갱신: 주기적으로 변동 가능

---

🔐 보안 원칙

✅ DO (반드시 해야 할 것)

• .env.local에만 실제 키 저장
• 서버 사이드 코드에서만 사용
• Git에 절대 커밋 금지
• 팀 공유 문서로 키 관리

❌ DON'T (절대 하지 말 것)

• 하드코딩 금지
• NEXT_PUBLIC_ 접두사 사용 금지
• 브라우저 코드에서 사용 금지
• 공개 저장소에 업로드 금지

---

📁 파일 구성

.env.local (실제 키 - Git 제외)

# API Key (서버 사이드 전용 - 절대 공개 금지!)
# 개발용 고정 키 (주기적 갱신 예정)
# 발급일: 2025-11-07
# 갱신 필요 시: PHP 백엔드 팀에 새 키 요청
API_KEY=42Jfwc6EaRQ04GNRmLR5kzJp5UudSOzGGqjmdk1a

.env.example (템플릿 - Git 커밋 OK)

# API Key (⚠️ 서버 사이드 전용 - 절대 공개 금지!)
# 개발팀 공유: 팀 내부 문서에서 키 값 확인
# 주기적 갱신: PHP 백엔드 팀에서 새 키 발급 시 업데이트 필요
API_KEY=your-secret-api-key-here

.gitignore 확인

# 라인 100-101에 이미 포함됨
.env.local
.env*.local

---

🔄 API Key 갱신 프로세스

1️⃣ PHP 팀에서 새 키 발급

PHP 백엔드 팀 → 새 API Key 발급
                ↓
         팀 공유 문서 업데이트

2️⃣ 로컬 개발 환경 업데이트

# .env.local 파일 열기
vi .env.local

# 또는
code .env.local

# API_KEY 값만 변경
API_KEY=새로운키값여기에입력

# 개발 서버 재시작
npm run dev

3️⃣ 프로덕션 환경 업데이트

Vercel 배포

# CLI로 업데이트
vercel env add API_KEY production

# 또는 대시보드에서
# Settings → Environment Variables → API_KEY 편집

AWS/기타 환경

# 환경 변수 업데이트
export API_KEY=새로운키값

# 또는 배포 설정에서 환경 변수 수정

4️⃣ 검증

# 개발 서버 시작 시 자동으로 검증됨
npm run dev

# 콘솔 출력 확인:
# 🔐 API Key Configuration:
#   ├─ Configured: ✅
#   ├─ Valid Format: ✅
#   ├─ Masked Key: 42Jf********************dk1a
#   └─ Length: 48 chars

---

🛠️ API Key 검증 유틸리티

자동 검증 기능

// lib/api/auth/api-key-validator.ts
import { apiKeyValidator } from '@/lib/api/auth/api-key-validator';

// 개발 서버 시작 시 자동 실행
console.log(apiKeyValidator.getDebugInfo());

// 출력 예시:
// API Key Status:
//   ├─ Configured: ✅
//   ├─ Valid Format: ✅
//   ├─ Masked Key: 42Jf********************dk1a
//   └─ Length: 48 chars

수동 검증

import { apiKeyValidator } from '@/lib/api/auth/api-key-validator';

// API Key 존재 확인
if (!apiKeyValidator.isConfigured()) {
  console.error('API Key not configured!');
}

// 형식 검증
if (!apiKeyValidator.isValid()) {
  console.error('Invalid API Key format!');
}

// 디버그 정보 출력
console.log(apiKeyValidator.getDebugInfo());

---

📊 사용 예시

서버 사이드 (Next.js API Route)

// app/api/sync/route.ts
import { createApiKeyClient } from '@/lib/api/auth/api-key-client';

export async function GET() {
  try {
    // 환경 변수에서 자동으로 키를 가져옴
    const client = createApiKeyClient();

    const data = await client.fetchData('/api/external-data');

    return Response.json({ success: true, data });
  } catch (error) {
    console.error('API request failed:', error);
    return Response.json(
      { error: 'Failed to fetch data' },
      { status: 500 }
    );
  }
}

백그라운드 스크립트

// scripts/sync-data.ts
import { createApiKeyClient } from '@/lib/api/auth/api-key-client';
import { apiKeyValidator } from '@/lib/api/auth/api-key-validator';

async function syncData() {
  // 1. 환경 변수 확인
  console.log(apiKeyValidator.getDebugInfo());

  if (!apiKeyValidator.isValid()) {
    throw new Error('Invalid API Key configuration');
  }

  // 2. API 요청
  const client = createApiKeyClient();
  const data = await client.fetchData('/api/sync-endpoint');

  console.log('Sync completed:', data);
}

syncData().catch(console.error);

---

⚠️ 에러 처리

API Key 미설정

❌ API_KEY is not configured!
📝 Please check:
   1. .env.local file exists
   2. API_KEY is set correctly
   3. Restart development server (npm run dev)

💡 Contact backend team if you need a new API key.

해결 방법:

1. .env.local 파일 생성 확인
2. API_KEY=실제키값 입력
3. npm run dev 재시작

API Key 형식 오류

❌ Invalid API Key format!
   - Minimum 32 characters required
   - Only alphanumeric characters allowed

해결 방법:

1. PHP 팀에서 발급받은 키 확인
2. 복사 시 공백/줄바꿈 없는지 확인
3. 정확한 키 값 재입력

---

🔍 만료 경고 (선택사항)

만료 체크 기능

// lib/api/auth/key-expiry-check.ts
import { apiKeyValidator } from './api-key-validator';

// API Key 발급일
const issuedDate = new Date('2025-11-07');

// 90일 유효기간으로 체크
const status = apiKeyValidator.checkExpiry(issuedDate, 90);

console.log(status.message);
// ✅ API Key valid (75 days left)
// ⚠️ API Key expiring in 10 days
// 🔴 API Key expired! Contact backend team.

if (status.isExpiring) {
  console.warn('⚠️ Please contact backend team for new API key!');
}

---

📚 체크리스트

초기 설정

• .env.local 파일 생성
• API_KEY 값 입력
• .gitignore에 .env.local 포함 확인
• 개발 서버 시작 후 검증 확인

키 갱신 시

• PHP 팀에서 새 키 수령
• .env.local 업데이트
• 로컬 개발 서버 재시작
• 검증 로그 확인
• 프로덕션 환경 변수 업데이트

보안 점검

• Git에 .env.local 커밋 안됨
• 브라우저 코드에서 사용 안함
• NEXT_PUBLIC_ 접두사 없음
• 팀 공유 문서에 키 기록

---

🚀 다음 단계

API Key 설정 완료 후:

1. createApiKeyClient() 사용하여 API 요청
2. 서버 사이드 코드에서만 호출
3. 에러 발생 시 검증 로그 확인
4. 주기적으로 만료 시간 체크 (선택)

---

📞 문의

• API Key 발급: PHP 백엔드 팀
• 기술 지원: 프론트엔드 팀
• 보안 문제: DevOps/보안 팀

---

관련 파일

프론트엔드

• src/lib/api/auth/api-key-client.ts - API Key 클라이언트
• src/lib/api/auth/api-key-validator.ts - API Key 검증 유틸리티
• src/app/api/sync/route.ts - 서버 사이드 API Route 예시

설정 파일

• .env.local - 환경 변수 (API_KEY 저장)
• .env.example - 환경 변수 템플릿
• .gitignore - Git 제외 설정