인증

Claude API는 요청을 인증하는 세 가지 방법을 지원합니다:

API 키와 Workload Identity Federation은 Claude API 엔드포인트에 동일한 접근 권한을 부여합니다. 빠르게 시작하려면 API 키를 선택하고, 워크로드에 이미 페더레이션할 수 있는 플랫폼 발급 ID가 있는 경우 Workload Identity Federation으로 전환하세요. 최종 사용자에게 배포하는 iOS 및 macOS 앱에는 App Attest를 사용하세요.



API 키

API 키는 Claude Console에서 생성하여 모든 요청에 전달하는 정적 시크릿입니다.

• 키 생성: Claude Console에서 Settings → API keys로 이동하세요. 생성 과정에서 만료 기간을 선택합니다. 워크스페이스를 사용하여 프로젝트 또는 환경별로 키의 범위를 지정하세요.
• 키 전송: 직접 HTTP 요청에서 x-api-key 헤더를 설정하거나, ANTHROPIC_API_KEY 환경 변수를 설정하면 클라이언트 SDK가 자동으로 이를 인식합니다.

POST /v1/messages
x-api-key: YOUR_API_KEY
anthropic-version: 2023-06-01
content-type: application/json

API 키는 시크릿 관리자에 저장하고, 주기적으로 교체하며, 유출이 의심되는 키는 즉시 폐기하세요. 또한 키를 생성할 때 만료 기간을 설정하여 유출된 자격 증명이 사용 가능한 기간을 제한할 수 있습니다.

client = Anthropic(api_key="my-anthropic-api-key")
# 또는 환경에 ANTHROPIC_API_KEY 가 설정된 경우:
client = Anthropic()



키 만료

Claude Console의 API keys 페이지에서 API 키를 생성할 때 만료 기간을 선택합니다: 사전 설정(3시간, 1일, 7일 또는 30일), 사용자 지정 기간, 또는 시크릿 관리자에 저장하고 직접 교체하는 키의 경우 Never를 선택할 수 있습니다. 조직에 최대 만료 정책이 있는 경우, Console은 사전 설정 및 사용자 지정 기간을 정책 최대값으로 제한하며 Never는 사용할 수 없습니다. 기존 키는 현재 동작을 유지합니다. 만료 기간은 생성 시점에 설정되며 이후에는 변경할 수 없습니다. Claude Console에서 Admin API 키를 생성할 때도 동일한 만료 선택이 적용됩니다.

Anthropic은 만료가 다가오면 키 생성자에게 이메일을 보냅니다: 수명이 14일 이상인 키의 경우 만료 7일 전에, 수명이 7일 이상인 키의 경우 만료 1일 전에 발송됩니다. 수명이 더 짧은 키는 경고 이메일 없이 만료됩니다.

키가 만료된 후 해당 키로 요청하면 401 authentication_error가 반환됩니다. 접근을 복원하려면 새 키를 생성하세요. 만료된 키는 재활성화할 수 없습니다.

Console의 API 키 테이블은 각 키의 만료 기간을 표시하며, Admin API는 List API Keys 및 Retrieve API Key 엔드포인트에서 각 키의 expires_at 타임스탬프를 보고하므로, 키가 만료되기 전에 감사하고 교체할 수 있습니다. 만료 기간이 없는 키의 경우 이 필드는 null입니다.

만료 기간은 유출된 자격 증명의 수명을 제한하지만, 시크릿 관리 위생을 대체하지는 않습니다. 만료 기간과 관계없이 키를 시크릿 관리자에 저장하고 유출이 의심되는 키는 즉시 폐기하세요.



Workload Identity Federation

"Workload Identity Federation"(워크로드 ID 페더레이션), 즉 WIF는 AWS IAM, Google Cloud 또는 표준을 준수하는 OIDC 발급자(예: GitHub Actions, Kubernetes 서비스 계정, SPIFFE, Microsoft Entra ID, Okta)와 같이 이미 신뢰하는 "identity provider"(ID 공급자), 즉 IdP가 발급한 단기 ID 토큰으로 워크로드를 인증할 수 있게 합니다. 워크로드는 IdP가 발급한 JWT를 POST /v1/oauth/token에서 단기 Claude API 액세스 토큰으로 교환하며, SDK는 토큰이 만료되기 전에 자동으로 갱신합니다. 발급, 배포 또는 교체해야 할 sk-ant-api... 문자열이 없습니다.

페더레이션은 환경에서 장기 Claude API 키를 제거하여 유출된 자격 증명의 피해 범위를 줄이고, 클라우드 리소스에 이미 사용하는 것과 동일한 IdP 제어로 접근을 관리할 수 있게 합니다. 그러나 페더레이션 자체만으로 종단 간 보안이 보장되는 것은 아닙니다. 신뢰 체인은 ID 공급자의 구성만큼만 강력하며, 한 단계 상위에 있는 장기 시크릿(예: IdP 토큰을 발급할 수 있는 정적 클라우드 자격 증명)이 여전히 이를 약화시킬 수 있습니다. 페더레이션을 IP 허용 목록, MFA, 감사 로깅과 같은 공급자의 제어 기능과 함께 사용하세요.

페더레이션을 구성하려면 Claude Console에서 세 가지 리소스(서비스 계정, 페더레이션 발급자, 페더레이션 규칙)를 생성한 다음 SDK가 해당 규칙을 가리키도록 설정합니다. 전체 설정 안내는 Workload Identity Federation을 참조하세요.



App Attest

App Attest는 기기에서 Claude API를 직접 호출하는 iOS 및 macOS 앱을 인증합니다. 각 설치는 Apple의 App Attest 서비스를 사용하여 Claude Console에 등록한 앱의 정품이며 수정되지 않은 빌드임을 증명합니다. 그런 다음 Anthropic은 기기에 단기 액세스 토큰을 발급하며, 사용량은 귀하의 워크스페이스에 청구됩니다. 토큰은 워크스페이스로 범위가 지정되고, 1시간 후 만료되며, Messages API 호출만 승인합니다.

앱을 등록하고 클라이언트 ID를 받으려면 iOS 및 macOS 앱용 App Attest를 참조하세요.



다음 단계