인증

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

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

API 키

API 키는 Claude Console에서 생성하고 모든 요청에서 Authorization 헤더에 bearer 토큰으로 전송하는 정적 시크릿입니다.

키 유형

키를 생성할 때 유형을 선택하며, 이는 키가 수행할 수 있는 작업, 작동하는 위치, 작동이 중지되는 시점을 결정합니다:

개인 키와 서비스 계정 키는 ID 기반입니다: 각각은 조직이 이미 관리하는 사용자 또는 서비스 계정에 속하며, 모든 요청은 해당 ID로 작동합니다. 해당 ID가 조직에서 제거되면 키가 작동을 멈춥니다. 이는 키가 소유한 사람이나 워크로드보다 실수로 오래 유지되지 않음을 의미합니다. 새 통합에는 워크스페이스 키보다 이를 선호하세요.

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

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

키 생성 및 사용

• 키 생성: Claude Console에서 설정 → API 키로 이동하여 Create key를 클릭하세요. 키 이름을 지정하고 만료를 선택하세요. 개인 키의 경우 Linked account를 본인으로 설정하거나, 여러 사용자 간에 공유되는 키의 경우 서비스 계정으로 설정하세요. 또한 키를 특정 워크스페이스로 범위를 지정할 수 있으며, 이렇게 하면 향후 요청에서 워크스페이스 ID를 수동으로 설정하는 것을 건너뛸 수 있습니다.
• 키 사용: 직접 HTTP 요청에서 Authorization: Bearer 로 전송하거나, ANTHROPIC_API_KEY 환경 변수를 설정하면 클라이언트 SDK가 자동으로 이를 가져옵니다.

POST /v1/messages
Authorization: Bearer YOUR_API_KEY
anthropic-version: 2023-06-01
content-type: application/json

레거시 x-api-key: YOUR_API_KEY 헤더는 Authorization 대신 여전히 지원됩니다.

API 키는 시크릿 관리자에 저장하고, 주기적으로 교체하며, 유출이 의심되는 키는 비활성화하거나 삭제하세요. API 키 페이지에서 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의 설정 → 워크스페이스에 있는 ID 열에서 확인하거나, List Workspaces 엔드포인트를 호출하여 확인할 수 있습니다. List Workspaces는 include_default=true를 전달한 경우에만 Default Workspace를 포함합니다. Default Workspace의 ID는 해당 워크스페이스에서 실행되는 모든 요청의 anthropic-workspace-id 응답 헤더에서도 확인할 수 있습니다.

client = Anthropic()  # reads ANTHROPIC_API_KEY

# 다중 워크스페이스 키의 경우 모든 요청에 필수입니다.
# 단일 워크스페이스 키의 경우 extra_headers를 생략하세요.
message = client.messages.create(
    model="claude-opus-5-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 `` not found. 메시지와 함께 404 not_found_error를 반환하며, 이는 알 수 없는 워크스페이스에 대한 응답과 동일합니다.

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

키 만료

Claude Console의 API 키 페이지에서 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. 필요한 경우 서비스 계정을 생성하세요. 조직 관리자에게 설정 → 서비스 계정에서 하나를 생성하고 관련 워크스페이스에 추가하도록 요청해야 할 수 있습니다.
3. 새 키를 생성하세요. 여러 워크스페이스가 필요하지 않은 한 통합의 워크스페이스용으로 구체적으로 생성하세요.
4. 새 키를 배포하세요. 통합이 키를 읽는 모든 곳, 일반적으로 ANTHROPIC_API_KEY 환경 변수 또는 시크릿 관리자 항목에서 이전 키를 교체하세요. 다중 워크스페이스 키의 경우, 워크스페이스 선택에 표시된 대로 anthropic-workspace-id 헤더도 전송하세요.
5. 이전 키를 삭제하세요. 요청이 성공하는지 확인한 다음, API 키 페이지에서 워크스페이스 키를 삭제하세요.

Workload Identity Federation

Workload Identity Federation(WIF)을 사용하면 워크로드가 AWS IAM, Google Cloud 또는 표준을 준수하는 모든 OIDC 발급자(예: GitHub Actions, Kubernetes 서비스 계정, SPIFFE, Microsoft Entra ID 또는 Okta)와 같이 이미 신뢰하는 자격 증명 공급자(IdP)가 발급한 단기 ID 토큰으로 인증할 수 있습니다. 워크로드는 POST /v1/oauth/token에서 IdP가 발급한 JWT를 단기 Claude API 액세스 토큰으로 교환하며, SDK는 만료되기 전에 해당 토큰을 자동으로 새로 고칩니다. 생성, 배포 또는 교체할 sk-ant-api... 문자열이 없습니다.

페더레이션은 환경에서 장기 Claude API 키를 제거하여 유출된 자격 증명의 영향 범위를 줄이고, 클라우드 리소스에 이미 사용하는 동일한 IdP 제어로 액세스를 관리할 수 있게 합니다. 그 자체로 엔드투엔드 보안을 보장하지는 않습니다: 신뢰 체인은 자격 증명 공급자의 구성만큼만 강력하며, 한 단계 상위의 장기 시크릿(예: 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를 참조하세요.

다음 단계