Claude API 키 발급과 안전한 환경변수 설정: .gitignore·유출 대응·Secret Manager 가이드 (2026)

요약: Claude API 키를 Console에서 발급하고 로컬 환경변수와 .gitignore로 보호하는 방법, 키가 노출됐을 때의 폐기·재발급 순서, 개발·운영 환경별 Secret Manager 분리 원칙을 단계별로 정리합니다.

Claude API를 처음 연결할 때 가장 중요한 원칙은 간단합니다. API 키를 코드에 쓰지 말고, 환경별로 다른 키를 사용하며, 노출이 의심되면 즉시 기존 키부터 폐기합니다. .env는 로컬 개발 편의를 위한 파일일 뿐 운영 환경의 비밀 저장소가 아닙니다.

이 글의 예제에 나오는 YOUR_CLAUDE_API_KEY는 작동하지 않는 가짜 값입니다. 실제 API 키를 문서, 채팅, 이슈, 이메일, 로그 또는 스크린샷에 붙여 넣지 마세요.

먼저 보는 결론

발급: Claude Console의 API Keys 페이지에서 환경별 키를 만듭니다.
로컬 개발: 키는 ANTHROPIC_API_KEY 환경변수 또는 Git에서 제외한 .env에 둡니다.
Git 보호: .env를 .gitignore에 추가하고 커밋 전에 git diff --cached로 확인합니다.
운영 배포: .env 파일을 서버에 복사하기보다 클라우드·호스팅의 암호화된 Secret Manager를 사용합니다.
환경 분리: 개발·테스트·운영 키를 나눕니다. 가능하면 비밀 저장소와 접근 권한도 환경별로 분리합니다.
유출 대응: 저장소 정리보다 키 폐기·재발급이 먼저입니다.

1. Claude API 키 발급하기

Claude API 키는 claude.ai 대화 화면이 아니라 Claude Console에서 관리합니다. Anthropic 공식 문서에 따르면 Console 계정과 API 키가 API 사용의 기본 준비 항목이며, 키는 API Keys 설정에서 생성합니다.

Claude Console에 로그인합니다.
API Keys 페이지를 엽니다.
키가 사용될 환경을 식별할 수 있게 이름을 정합니다. 예: myapp-dev, myapp-prod.
적절한 만료 기간을 선택해 키를 생성합니다. Anthropic은 키 생성 시 만료 기간을 선택하도록 안내합니다.
표시된 키를 즉시 안전한 위치에 저장합니다. 이 글이나 다른 온라인 문서에 실제 값을 붙여 넣지 않습니다.

소규모 팀이라도 한 키를 모두가 공유하지 않는 편이 좋습니다. Anthropic은 API 접근이 필요한 사람에게 각자의 키를 사용하도록 하고, 개발·테스트·운영 목적에도 서로 다른 키를 사용할 것을 권장합니다.

Workspace는 언제 나누면 좋을까?

Anthropic 공식 API 개요는 Workspaces를 사용해 용도별로 API 키와 지출을 구분할 수 있다고 설명합니다. 서비스가 하나뿐인 초기 단계라면 우선 개발 키와 운영 키를 분리하는 것부터 시작해도 됩니다. 여러 서비스나 팀이 생기면 Workspace도 서비스·용도 단위로 나누면 사용량 추적과 사고 범위 제한이 쉬워집니다.

Workspace 분리와 Secret Manager 분리는 서로 다른 문제입니다.

Claude Workspace: Anthropic Console 안에서 키·사용량·지출을 용도별로 구분
Secret Manager: 애플리케이션이 실행되는 인프라에서 비밀값을 암호화해 저장하고 접근 권한을 통제

2. 로컬 개발에서는 환경변수로 읽기

macOS·Linux: 현재 터미널 세션에만 설정

export ANTHROPIC_API_KEY="YOUR_CLAUDE_API_KEY"

이 방식은 해당 터미널 세션이 끝나면 사라집니다. 키가 셸 기록에 남을 수 있으므로 공유 PC에서는 주의하고, 명령 화면을 캡처하거나 복사해 공유하지 마세요.

Windows PowerShell: 현재 세션에만 설정

$env:ANTHROPIC_API_KEY = "YOUR_CLAUDE_API_KEY"

키를 출력하지 않고 설정 여부만 확인

if [ -n "$ANTHROPIC_API_KEY" ]; then
  echo "ANTHROPIC_API_KEY is set"
else
  echo "ANTHROPIC_API_KEY is missing"
fi

echo $ANTHROPIC_API_KEY처럼 실제 값을 화면에 출력하지 마세요. 터미널 로그, 화면 공유, CI 로그에 남을 수 있습니다.

인증 연결 확인

아래 요청은 환경변수 값을 x-api-key 헤더에 넣고 Anthropic의 Models API를 조회합니다. 키 자체를 출력하지 않습니다.

curl --fail-with-body --silent --show-error \
  https://api.anthropic.com/v1/models \
  --header "x-api-key: $ANTHROPIC_API_KEY" \
  --header "anthropic-version: 2023-06-01"

Anthropic SDK를 사용하면 ANTHROPIC_API_KEY를 자동으로 읽을 수 있습니다. 키를 소스 코드의 문자열 인수로 직접 넣을 필요가 없습니다.

import os
from anthropic import Anthropic

if not os.environ.get("ANTHROPIC_API_KEY"):
    raise RuntimeError("ANTHROPIC_API_KEY is missing")

client = Anthropic()  # ANTHROPIC_API_KEY 환경변수를 자동으로 읽음

실제 메시지 호출 코드를 작성할 때는 모델 이름을 임의로 추측하지 말고, 위 Models API 또는 공식 모델 문서에서 현재 사용할 수 있는 모델 ID를 확인하세요.

3. `.env`를 쓴다면 `.gitignore`가 먼저다

로컬에서 python-dotenv 같은 도구를 사용한다면 프로젝트 루트의 .env에 키를 둘 수 있습니다.

ANTHROPIC_API_KEY=YOUR_CLAUDE_API_KEY

하지만 .env를 만들기 전에 .gitignore를 준비하세요.

# Local environment files
.env
.env.*
!.env.example

팀이 필요한 변수 이름을 알 수 있도록 값이 빈 .env.example만 저장소에 커밋합니다.

ANTHROPIC_API_KEY=

Git이 .env를 무시하는지 확인합니다.

git check-ignore -v .env
git status --short

커밋 직전에는 스테이징된 변경을 다시 봅니다.

git diff --cached

`.gitignore`를 추가했는데도 `.env`가 계속 보인다면

이미 추적 중인 파일은 .gitignore에 추가해도 자동으로 추적 해제되지 않습니다. 아직 외부에 공개되지 않았고 키도 노출되지 않았다는 전제에서 다음처럼 Git 인덱스에서만 제거할 수 있습니다.

git rm --cached .env
git commit -m "Stop tracking local environment file"

단, .env가 과거 커밋이나 원격 저장소에 들어갔다면 이 명령만으로 사고가 해결되지 않습니다. 먼저 키를 폐기하고 새 키로 교체한 뒤, 필요하면 Git 기록 정리를 검토해야 합니다.

4. 브라우저 코드에 키를 넣으면 안 된다

ANTHROPIC_API_KEY는 서버에서만 읽어야 합니다. React·Vue·정적 HTML처럼 사용자의 브라우저로 내려가는 코드에 키를 포함하면 개발자 도구와 번들 파일에서 확인될 수 있습니다.

특히 NEXT_PUBLIC_, VITE_처럼 클라이언트에 공개하도록 설계된 접두사가 붙은 변수에 Claude API 키를 넣지 마세요.

안전한 기본 구조는 다음과 같습니다.

사용자 브라우저 → 내 서버/API 라우트 → Claude API
                         ↑
                 Secret Manager에서 키 주입

브라우저는 내 서버에 요청하고, Claude API 호출은 비밀키를 가진 서버가 수행합니다. 서버 로그에도 요청 헤더나 환경변수 전체를 출력하지 않도록 설정합니다.

5. 개발·CI·운영 환경의 비밀 관리 기준

환경	권장 저장 위치	키	접근 원칙
개인 로컬 개발	현재 셸 환경변수 또는 Git에서 제외한 `.env`	개발 전용	개발자 본인만 접근
CI/CD	GitHub Actions 등 배포 플랫폼의 암호화된 Secrets	CI 또는 배포 전용	해당 워크플로에 필요한 최소 권한
스테이징	스테이징용 Secret Manager·프로젝트·Vault	스테이징 전용	스테이징 실행 주체만 읽기
운영	운영용 Secret Manager·프로젝트·Vault	운영 전용	운영 서비스 계정만 읽기, 사람의 상시 조회는 제한

운영에서는 다음 원칙을 적용합니다.

개발과 운영에 같은 키를 쓰지 않습니다. 한 환경의 사고가 다른 환경으로 번지는 것을 줄일 수 있습니다.
비밀 저장소도 환경별로 격리합니다. 가능하면 개발·스테이징·운영을 별도 프로젝트, 계정 또는 Vault로 나눕니다.
최소 권한을 적용합니다. 운영 애플리케이션의 실행 주체에는 해당 운영 비밀을 읽는 권한만 줍니다.
소스 코드와 컨테이너 이미지에 키를 넣지 않습니다. 빌드 시 복사하지 말고 실행 시점에 주입합니다.
키 이름과 소유자를 기록합니다. 예: 서비스, 환경, 발급일, 만료일, 담당자. 실제 키 값은 운영 문서에 적지 않습니다.
교체 절차를 미리 시험합니다. 새 키 저장 → 배포 또는 재시작 → 정상 동작 확인 → 이전 키 폐기 순서를 서비스 중단 없이 수행할 수 있어야 합니다.
사용량과 로그를 정기 확인합니다. 예상하지 못한 호출 패턴을 발견할 수 있도록 Console의 로그·사용량을 점검합니다.

대표적인 운영용 비밀 저장소는 AWS Secrets Manager, Google Cloud Secret Manager, Azure Key Vault입니다. 사용 중인 호스팅이 별도의 암호화된 Secrets 기능을 제공한다면 그 기능을 사용해도 됩니다.

환경변수는 애플리케이션에 비밀을 전달하는 방법이고, Secret Manager는 비밀을 저장·권한 통제·감사하는 시스템입니다. 운영에서는 Secret Manager에 보관한 값을 실행 시 환경변수나 파일 마운트 등 플랫폼이 지원하는 방식으로 주입합니다.

6. Claude API 키가 유출됐거나 의심된다면

GitHub 공식 문서는 비밀번호·토큰·자격증명 같은 비밀이 노출됐을 때 가장 먼저 해당 비밀을 폐기하거나 교체하라고 안내합니다. 저장소 기록을 지우는 작업보다 이 조치가 먼저입니다.

즉시 대응 순서

기존 키를 즉시 폐기합니다. Claude Console API Keys 페이지에서 문제가 된 키를 삭제합니다.
새 키를 발급합니다. 같은 키를 다시 저장하거나 이름만 바꾸지 말고 새로운 키를 만듭니다.
영향받은 환경의 Secret만 교체합니다. 개발 키 유출이라면 개발 환경만, 운영 키 유출이라면 운영 Secret Manager와 배포 환경을 우선 갱신합니다.
애플리케이션을 재배포하거나 재시작합니다. 새 값이 실제 프로세스에 반영됐는지 확인합니다.
Claude Console의 로그와 사용량을 검토합니다. 평소와 다른 호출이 있었는지 확인하고 내부 사고 기록을 남깁니다.
노출 경로를 제거합니다. 코드, CI 로그, 이슈, 채팅, 문서, 컨테이너 이미지 등 키가 복제된 위치를 확인합니다.
재발 방지를 적용합니다. .gitignore, Secret scanning, Push protection, pre-commit 검사를 추가합니다.

Anthropic은 공개 GitHub 저장소에서 노출된 Claude API 키를 GitHub가 탐지해 Anthropic에 알리면 해당 키를 자동 비활성화하고 사용자에게 알릴 수 있다고 설명합니다. 그러나 알림을 기다리지 말고, 노출이 의심되는 즉시 Console에서 상태를 확인하고 기존 키를 폐기한 뒤 새 키로 교체하세요.

Git 기록에서도 지워야 할까?

키를 폐기하면 기존 값으로 더 이상 인증할 수 없습니다. 이것이 최우선 조치입니다. Git 기록 정리는 다음 단계이며, 저장소의 민감 정보 제거 요구나 내부 정책에 따라 판단합니다.

GitHub는 기록 재작성에 커밋 해시 변경, 협업자 저장소의 재오염, Pull Request 영향 같은 부작용이 있다고 경고합니다. 필요하다면 GitHub의 민감 정보 제거 절차를 따라 협업자와 조율하세요. 키를 단순히 최신 커밋에서 삭제하거나 저장소를 비공개로 바꾸는 것만으로는 과거 복사본까지 사라지지 않습니다.

7. GitHub에서 한 단계 더 막기

.gitignore는 필요한 기본 장치지만 이미 추적된 파일, 다른 파일에 하드코딩한 값, 터미널에서 강제로 추가한 파일까지 모두 막아 주지는 않습니다.

Secret scanning: 저장소와 Git 기록에서 알려진 형식의 비밀을 탐지합니다.
Push protection: 하드코딩된 자격증명이 저장소로 푸시되기 전에 차단하도록 돕습니다.
커밋 전 검토: git diff --cached로 실제 커밋 내용을 확인합니다.
사전 검사 도구: 필요하면 gitleaks 같은 도구를 pre-commit 또는 CI에 연결합니다.

GitHub 기능의 제공 범위와 설정 방법은 저장소 공개 여부, 조직 정책, 사용 플랜에 따라 달라질 수 있으므로 현재 저장소의 보안 설정과 공식 문서를 확인하세요.

실무 체크리스트

발급 전

개발·테스트·운영 중 어느 환경의 키인지 이름으로 구분했다.
필요한 경우 Claude Workspace를 용도별로 분리했다.
키 만료와 교체 담당자를 정했다.
실제 키를 문서나 메신저로 공유하지 않기로 합의했다.

로컬 개발

키는 ANTHROPIC_API_KEY로 읽는다.
.env와 환경별 .env.*는 .gitignore에 포함했다.
값이 빈 .env.example만 커밋한다.
git check-ignore -v .env로 제외 여부를 확인했다.
git diff --cached로 비밀값이 없는지 확인했다.
브라우저 번들 또는 공개 접두사 변수에 키를 넣지 않았다.

운영 배포

개발·스테이징·운영 키가 서로 다르다.
운영 키는 Secret Manager 또는 호스팅의 암호화된 Secrets에 저장했다.
운영 비밀 저장소와 접근 권한을 비운영 환경에서 분리했다.
실행 서비스 계정에 필요한 읽기 권한만 부여했다.
로그와 오류 메시지에 API 키·요청 헤더·전체 환경변수가 출력되지 않는다.
키 교체 후 재배포·재시작과 정상 동작 확인 절차가 있다.
Secret scanning 또는 Push protection을 검토했다.

유출 의심 시

저장소 수정 전에 기존 키부터 폐기했다.
새 키를 발급해 영향받은 환경에만 반영했다.
애플리케이션을 재배포 또는 재시작했다.
Console 로그와 사용량을 확인했다.
Git 기록, CI 로그, 이슈, 문서, 이미지 등 복제 위치를 점검했다.
원인을 기록하고 재발 방지 설정을 추가했다.

자주 묻는 질문

`.env`에 넣으면 완전히 안전한가요?

아닙니다. .env는 평문 파일입니다. Git에서 제외하고 파일 접근 권한을 제한해야 하며, 운영 환경에서는 암호화된 Secret Manager를 우선 사용하세요.

`.gitignore`를 나중에 추가해도 되나요?

새 파일은 제외할 수 있지만 이미 커밋된 내용은 과거 기록에 남을 수 있습니다. 키가 한 번이라도 커밋됐다면 공개 여부와 관계없이 기존 키 폐기·재발급부터 진행하는 것이 안전합니다.

개발 키와 운영 키를 꼭 나눠야 하나요?

Anthropic은 가능하면 개발·테스트·운영 목적에 서로 다른 키를 사용하도록 권장합니다. 키를 나누면 사용량을 구분하고, 한 환경의 키만 빠르게 중지할 수 있습니다.

운영에서도 환경변수를 쓰면 안 되나요?

환경변수 자체가 금지되는 것은 아닙니다. 핵심은 운영 키의 원본을 소스나 .env 배포 파일에 두지 않고 Secret Manager에서 관리한 뒤, 플랫폼이 지원하는 안전한 방식으로 실행 프로세스에 주입하는 것입니다.

키를 GitHub에서 삭제했는데 재발급도 해야 하나요?

네. 삭제 커밋만으로는 과거 기록, 포크, 클론, 캐시에서 값이 사라졌다고 보장할 수 없습니다. 기존 키를 즉시 폐기하고 새 키를 발급하세요.

공식 출처

다음 문서는 2026년 7월 19일 확인했습니다.

Anthropic·Claude 공식 문서

Claude Platform Docs — API overview — Console에서의 키 생성, 인증 헤더, Workspaces를 통한 키·지출 구분
Claude Platform Docs — Get started with Claude — ANTHROPIC_API_KEY 환경변수와 SDK 기본 설정
Claude Platform Docs — Authentication — API 키 생성과 만료 설정
Claude Help Center — API Key Best Practices: Keeping Your Keys Safe and Secure — 키 공유 금지, 환경변수·Secret Manager, .gitignore, 환경별 키 분리, 모니터링, 유출 시 폐기
Claude Help Center — What should I do if I suspect my API key has been compromised? — 의심 시 즉시 키 폐기 절차
Claude Help Center — Creating and managing Workspaces in the Claude Console — Workspace와 API 키 관리

GitHub 공식 문서

GitHub Docs — Removing sensitive data from a repository — 키 폐기·교체 우선, .gitignore, 환경변수·Secret Manager, 기록 재작성 주의점
GitHub Docs — About secret scanning — 저장소와 기록의 비밀 탐지
GitHub Docs — Push protection — 하드코딩된 비밀의 푸시 차단

운영용 Secret Manager 공식 문서

함께 읽을 가이드

공식 문서 확인 기준일: 2026년 7월 19일. 가격·모델·할당량은 변경될 수 있으므로 실행 전 연결된 공식 문서를 다시 확인하세요.

'🤖 1인 에이전트 구축기' 카테고리의 다른 글

n8n 워크플로우 무중단 운영을 위한 예외 처리 및 대체 모델 필수 체크리스트 (0)	2026.06.12
Gemini·Claude 교차검증 가이드: LLM 합의보다 근거를 비교하는 방법 (0)	2026.05.27
Claude API 재시도 설계: Node.js에서 중복과 장애를 함께 다루는 방법 (0)	2026.05.23
API Rate Limit 대응: 429 재시도·백오프·동시성 제한 설계 (0)	2026.05.23
Gemini API 시작 가이드: API 키 발급부터 Python 첫 호출까지 (0)	2026.05.13