인증

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

API 키와 Workload Identity Federation은 Claude API 엔드포인트에 대해 동일한 액세스 권한을 부여합니다. 빠르게 시작하려면 API 키를 선택하세요. 본인의 개발용으로는 개인 키를, 공유되는 모든 용도에는 서비스 계정 키를 사용합니다. 워크로드에 이미 페더레이션할 수 있는 플랫폼 발급 ID가 있다면 Workload Identity Federation으로 전환하세요. 최종 사용자에게 배포하는 iOS 및 macOS 앱에는 App Attest를 사용하세요.

API 키

"API key"(API 키)는 Claude Console에서 생성하여 모든 요청의 x-api-key 헤더에 담아 보내는 정적 시크릿입니다.

키 유형

키를 생성할 때 키 유형을 선택하며, 이 유형에 따라 키가 무엇을 할 수 있는지, 어디에서 작동하는지, 언제 작동을 멈추는지가 결정됩니다:

개인 키와 서비스 계정 키는 ID 기반(identity-backed)입니다. 각 키는 조직에서 이미 관리하고 있는 사용자 또는 서비스 계정에 속하며, 모든 요청은 해당 ID로서 수행됩니다. 해당 ID가 조직에서 제거되면 키는 작동을 멈춥니다. 즉, 키가 이를 소유한 사람이나 워크로드보다 의도치 않게 오래 살아남는 일이 없습니다. 새로운 통합에는 워크스페이스 키보다 이러한 키를 우선적으로 사용하세요.

본인의 개발 및 스크립트에는 개인 키를 사용하세요. 공유된 개인 키는 한 사람으로서 동작하며 그 사람이 떠나면 작동하지 않게 됩니다. 공유 또는 자동화된 워크로드(CI, 프로덕션 서비스)의 경우, 조직 관리자에게 서비스 계정을 생성하도록 요청하여 워크로드가 자체 ID를 갖도록 하세요.

워크스페이스 API 키는 여전히 작동하지만 레거시로 간주해야 합니다. ID 기반 키 또는 Workload Identity Federation이 권장됩니다. 마이그레이션하려면 워크스페이스 API 키 교체를 참조하세요.

키 생성 및 사용

• 키 생성: Claude Console의 Settings → API keys로 이동하여 Create key를 클릭하세요. 키 이름을 지정하고 만료를 선택하세요. 개인 키의 경우 Linked account를 본인으로, 여러 사용자가 공유하는 키의 경우 서비스 계정으로 설정하세요. 키의 범위를 특정 워크스페이스로 지정할 수도 있으며, 이렇게 하면 이후 요청에서 워크스페이스 ID를 수동으로 설정하지 않아도 됩니다.
• 키 사용: 직접 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 키는 시크릿 관리자에 저장하고, 주기적으로 교체하며, 유출이 의심되는 키는 비활성화하거나 삭제하세요. API keys 페이지에서 Disable은 되돌릴 수 있는 반면(Admin API는 키의 status를 "inactive"로 보고하며, Re-enable하면 "active"로 돌아갑니다), Delete는 영구적입니다. 키는 보관 처리되며 List API Keys에 status: "archived"로 계속 표시됩니다. 만료된 키는 삭제만 가능합니다. 또한 키를 생성할 때 만료를 설정하여 유출된 자격 증명이 사용 가능한 기간을 제한할 수 있습니다.

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

워크스페이스 선택

특정 워크스페이스용으로 생성된 API 키는 해당 워크스페이스에서만 작동하며, 이러한 키를 사용하는 API 요청은 워크스페이스 ID를 생략할 수 있습니다.

API 키의 범위가 워크스페이스로 지정되어 있지 않다면, 각 요청의 anthropic-workspace-id 헤더에 워크스페이스 ID를 지정해야 합니다. 요청 또는 SDK에서 이 헤더를 설정하는 방법은 다음 예시를 참조하세요.

Admin API는 키의 범위가 특정 워크스페이스로 지정되어 있지 않은 경우에만 개인 키 또는 서비스 계정 키를 허용합니다.

워크스페이스의 ID는 Claude Console의 Settings → Workspaces에 있는 ID 열에서 확인하거나, List Workspaces 엔드포인트를 호출하여 확인할 수 있습니다. 둘 다 Default Workspace의 ID는 나열하지 않습니다. 해당 워크스페이스에서 실행되는 임의의 요청(예: Default Workspace의 워크스페이스 키로 수행한 요청)의 anthropic-workspace-id 응답 헤더에서 읽거나, List API Keys에서 해당 키의 scope.workspace_id에서 읽으세요.

client = Anthropic()  # reads ANTHROPIC_API_KEY

# 다중 워크스페이스 키의 경우 모든 요청에 필수입니다.
# 단일 워크스페이스 키의 경우 extra_headers를 생략하세요.
message = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
    extra_headers={"anthropic-workspace-id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ"},
)
print(message.content)

# 또는 이 클라이언트의 모든 요청에 대해 한 번만 설정하세요:
workspace_client = Anthropic(
    default_headers={"anthropic-workspace-id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ"},
)

범위가 워크스페이스로 지정되지 않은 키로 수행한 요청에서 이 헤더를 생략하면, API는 400 invalid_request_error를 반환합니다:

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "anthropic-workspace-id is required when authenticating with an identity-linked API key; send the id of the workspace this request acts in."
  },
  "request_id": "req_011CSHoEeqs5C35K2UUqR7Fy"
}

유효한 워크스페이스 ID가 아닌 헤더 값은 anthropic-workspace-id header must be a valid workspace ID. 메시지와 함께 400 invalid_request_error를 반환합니다. 워크스페이스가 존재하지 않거나 키의 사용자 또는 서비스 계정이 해당 워크스페이스에 액세스할 수 없는 경우, API는 Workspace `<id>` not found. 메시지와 함께 404 not_found_error를 반환하며, 이는 알 수 없는 워크스페이스에 대한 응답과 동일합니다.

Workload Identity Federation은 대신 토큰 교환 시점에 워크스페이스를 선택합니다. 자세한 내용은 WIF 레퍼런스를 참조하세요.

키 만료

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입니다.

만료는 유출된 자격 증명의 수명을 제한하지만, 시크릿 위생 관리를 대체하지는 않습니다. 만료 여부와 관계없이 키를 시크릿 관리자에 저장하고, 유출이 의심되는 키는 비활성화하거나 삭제하세요.

워크스페이스 API 키 교체

워크스페이스 키가 있다면 Workload Identity Federation 또는 개인 키나 서비스 계정 키로 교체하는 것이 좋습니다. 이렇게 하면 보안과 관측 가능성이 향상됩니다.

장기 키보다 권장되는 Workload Identity Federation 구성에 대한 자세한 내용은 Workload Identity Federation을 참조하세요.

워크스페이스 키를 개인 키 또는 서비스 계정 키로 교체하려면:

1. 키 유형을 결정합니다. 본인의 도구에는 개인 키를 사용해야 합니다. 공유되거나 무인으로 운영되는 워크로드에는 서비스 계정 키를 사용해야 합니다.
2. 필요한 경우 서비스 계정을 생성합니다. 조직 관리자에게 Settings → Service accounts에서 서비스 계정을 생성하고 관련 워크스페이스에 추가하도록 요청해야 할 수 있습니다.
3. 새 키를 생성합니다. 여러 워크스페이스가 필요한 경우가 아니라면 통합 대상 워크스페이스 전용으로 생성하세요.
4. 새 키를 배포합니다. 통합이 키를 읽는 모든 위치(일반적으로 ANTHROPIC_API_KEY 환경 변수 또는 시크릿 관리자 항목)에서 이전 키를 교체하세요. 다중 워크스페이스 키의 경우 워크스페이스 선택에 표시된 대로 anthropic-workspace-id 헤더도 함께 보내세요.
5. 이전 키를 삭제합니다. 요청이 성공하는지 확인한 다음 API keys 페이지에서 워크스페이스 키를 삭제하세요.

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를 참조하세요.

다음 단계