SSD Nodes Learn Hosting plans →
가이드 Matt Connor작성자 Matt Connor

Claude API 인증: key, Bedrock, Vertex, Foundry

VPS에서 Claude API 클라이언트를 인증하는 4개 경로를 설명합니다. Anthropic key, AWS IAM, Google ADC, Microsoft Entra의 전송 방식과 서버 자격 증명 보관법을 확인합니다.

Claude API 인증 경로

Claude API 인증은 클라이언트가 네트워크로 어떤 자격 증명을 전송할지 결정하는 문제로 귀결됩니다. Anthropic은 직접 제공하는 Claude API 외에도 Amazon Bedrock, AWS의 Claude Platform, Google Cloud의 Claude Models(Google 관리형), Google Cloud의 Claude Models(Anthropic 관리형), Microsoft Foundry 등 5가지 클라우드 플랫폼을 지원합니다. Anthropic 직접 API는 Authorization: Bearer 헤더에 API 키나 단기 토큰을 사용하며, 레거시 x-api-key 헤더를 통한 API 키도 여전히 허용합니다. Amazon Bedrock은 AWS 요청 서명과 Bedrock API 키를 지원하며, 해당 설정에는 Anthropic 키가 사용되지 않습니다. Google Cloud는 단기 Google 액세스 토큰을 전송합니다. Microsoft Foundry는 Azure에서 발급한 키나 Microsoft Entra 토큰을 사용합니다. 아래 4개 섹션에서는 이러한 자격 증명 설정 방법을 다루며, Anthropic이 관리하는 AWS 및 Google Cloud 제품군은 각 클라우드 대응 항목과 함께 설명합니다.

이 가이드는 Linux 서버에서 실행되는 서비스에 SDK(소프트웨어 개발 키트)를 연결하기 위한 것입니다. 만약 Claude Code 명령줄 도구를 구성하는 중이라면 변수와 흐름이 다르므로 Bedrock 또는 Vertex에 Claude Code 연결하기를 참조하십시오. 서비스가 아직 없다면 VPS에서 첫 번째 Claude API 앱 만들기를 통해 먼저 구축한 뒤 자격 증명 설정을 위해 다시 돌아오십시오.

이하의 모든 내용은 2026년 8월 Anthropic 플랫폼 문서를 기준으로 확인되었으며, 2026년 10월 16일에 각 제공업체의 문서와 대조하여 재검토되었습니다. Bedrock 모델 접근 세부 정보는 2026년 10월 19일 AWS 문서를 기준으로 재확인되었습니다. 4개 경로 전체에 대한 Anthropic 페이지, API 키 및 API 버전 정보는 2026년 10월 27일에 재검토되었습니다. Microsoft Foundry, 두 가지 Bedrock 엔드포인트, Google 관리형 경로, AWS의 Claude Platform, 인증, Workload Identity Federation 및 API 버전에 관한 Anthropic 페이지는 2026년 11월 10일에 Ruby SDK 변경 로그와 함께 재검토되었습니다. 모델 식별자, 가격, SDK 버전 및 엔드포인트 형태는 수시로 변경되므로, 이 가이드에서는 정보가 노후화될 수 있는 값을 직접 기재하는 대신 제공업체의 페이지 링크를 제공합니다.

경로 1: Anthropic API 키

이 경로는 직접 연결하는 방식이며, Anthropic이 비밀 값을 발급하는 유일한 경로입니다. 요청은 Anthropic의 API 호스트에 있는 Messages endpoint로 전송되며, 모든 요청에는 3개의 헤더가 포함됩니다.

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model": "MODEL_ID", "max_tokens": 64, "messages": [{"role": "user", "content": "Hello"}]}'

MODEL_ID을 Anthropic의 models overview에서 확인한 현재 식별자로 바꿉니다. 정상 응답은 content 배열과 usage 객체를 포함하는 JSON입니다. 잘못되었거나 만료된 키를 사용하면 authentication_error과 함께 HTTP 401이 반환됩니다. anthropic-version 헤더가 없으면 별도의 오류가 발생합니다. 이 헤더는 모든 요청에 필요하며 SDK가 자동으로 설정합니다. 2026년 10월 기준으로 Anthropic 문서는 키를 전송하는 기본 방식으로 Authorization: Bearer을 제시하고 x-api-key를 레거시 방식으로 부릅니다. 그러나 두 방식 모두 허용되므로 위 명령은 계속 작동합니다. 현재 SDK 주요 버전도 키를 Authorization: Bearer로 전송합니다. 따라서 X-Api-Key을 읽는 프록시나 게이트웨이는 SDK를 업그레이드할 때 수정해야 합니다. 명령에 사용된 2023-06-01 버전은 여전히 허용됩니다. Anthropic의 최신 API 버전은 2026-10-21이며, 해당 SDK 버전은 이 값을 기본으로 전송합니다. 이 버전은 temperature와 같은 일부 이전 요청 매개변수를 거부합니다.

이 설정에서는 구성할 것이 없으므로 클라이언트 생성이 가장 간단합니다. 모든 공식 SDK가 환경에서 ANTHROPIC_API_KEY을 자체적으로 읽습니다.

import os
from anthropic import Anthropic

client = Anthropic()  # reads ANTHROPIC_API_KEY from the environment

message = client.messages.create(
    model=os.environ["CLAUDE_MODEL"],
    max_tokens=64,
    messages=[{"role": "user", "content": "Hello"}],
)
print(message.usage)

키와 함께 모델 식별자를 환경 변수에 저장하는 것이 좋습니다. 모델 이름은 사용자가 통제할 수 없는 일정에 따라 변경되므로, 문자열 하나를 수정하려고 코드를 다시 배포하는 일은 피할 수 있는 작업입니다.

키는 Console에서 생성합니다. 생성할 때 만료 기간을 선택합니다. 선택지는 3 hours, 1 day, 7 days 또는 30 days 사전 설정, 사용자 지정 기간, Never이며, 조직의 최대 만료 정책이 적용됩니다. 만료 기간은 생성할 때 고정되며 나중에 변경할 수 없습니다. Anthropic은 장기간 유효한 키가 만료되기 전에 키 생성자에게 이메일을 보냅니다. 그러나 수명이 짧은 키가 만료될 때는 경고 이메일을 전혀 보내지 않습니다. 만료된 키는 401을 반환하며 다시 활성화할 수 없습니다. 따라서 항상 새 키를 발급해야 합니다.

직접 API에서는 선택할 리전이 없으며 요금은 Anthropic 조직에 직접 청구됩니다. Workspace를 사용하면 키의 범위를 하나의 프로젝트로 제한할 수 있으므로, 단일 서비스의 비용을 확인하는 가장 명확한 방법입니다. 서버용 키를 생성할 때 해당 키의 범위를 Workspace로 제한합니다. Workspace 범위가 지정되지 않은 개인 키나 서비스 계정 키는 모든 요청에 anthropic-workspace-id 헤더를 보내야 합니다. 그렇지 않으면 API가 invalid_request_error과 함께 400을 반환합니다. 서비스에는 서비스 계정 키를 사용합니다. 키를 만든 사람이 조직을 떠나면 개인 키는 작동하지 않기 때문입니다. 요금 계산 방식은 토큰별 API 가격과 구독 요금 비교를 참조하십시오.

여기서 한 가지 선택지를 더 고려할 수 있습니다. 이 방식은 정적 비밀 값을 완전히 제거합니다. Workload Identity Federation을 사용하면 이미 신뢰하는 identity provider의 OpenID Connect (OIDC) 토큰을 POST /v1/oauth/token에서 단기간 유효한 Anthropic 토큰으로 교환할 수 있으며, SDK가 토큰이 만료되기 전에 갱신합니다. 어떤 곳에서도 sk-ant-api... 문자열을 발급하거나 복사하지 않습니다. 이미 플랫폼 identity를 보유한 Kubernetes, GitHub Actions 및 cloud VM에 적합합니다. 일반적인 VPS에는 대개 이러한 issuer가 없습니다. 따라서 해당 서버에서는 파일에 API 키를 저장하는 것이 현실적인 방법이며, 이 가이드의 나머지 내용도 이를 전제로 합니다.

경로 2: Amazon Bedrock에서 AWS 자격 증명 사용

Bedrock에서는 Anthropic 키를 전혀 보유하지 않습니다. AWS 자격 증명을 사용하면 SDK가 각 HTTP 요청에 AWS Signature Version 4(SigV4)로 서명하며, AWS는 해당 호출자가 모델을 호출할 수 있는지 결정합니다.

pip install -U "anthropic[bedrock]"
aws sts get-caller-identity

aws sts get-caller-identity은 자격 증명이 확인하는 ID의 계정 번호와 ARN(Amazon Resource Name)을 출력합니다. SigV4를 사용할 때는 다른 어떤 작업보다 먼저 이 명령을 실행하십시오. SigV4의 경우 SDK는 생성자 자격 증명, 환경 자격 증명 및 표준 AWS 자격 증명 체인을 확인합니다. 리전 선택은 별도로 이루어집니다. Python의 AnthropicBedrock 클라이언트에서 api_key 또는 AWS_BEARER_TOKEN_BEDROCK을 통해 Bedrock API 키를 제공할 때 aws_access_key, aws_secret_key, aws_session_token 또는 aws_profile을 함께 전달하면 ValueError이 발생합니다. 이러한 명시적 인수 없이 키를 사용하면 AWS 자격 증명 체인 대신 베어러 인증이 선택됩니다. TypeScript 클라이언트는 명시적 AWS 자격 증명보다 Bedrock API 키를 우선합니다. STS 명령은 베어러 인증을 테스트하지 않습니다.

클라이언트 구성에서 변경되는 것은 클래스와 인수 하나뿐입니다.

from anthropic import AnthropicBedrock

client = AnthropicBedrock(aws_region="us-east-1")

AnthropicBedrock는 Bedrock의 InvokeModel 통합을 구동합니다. 2026년 10월 기준으로 Anthropic은 Claude Opus 4.7 및 이후 모델을 위한 https://bedrock-mantle.{region}.api.aws/anthropic/v1/messages의 Messages API 엔드포인트인 Amazon Bedrock의 Claude도 문서화하고 있으며, 이는 동일한 패키지의 AnthropicBedrockMantle 클라이언트를 통해 접근합니다. 이 엔드포인트는 AWS 자격 증명과 Bedrock 베어러 토큰을 모두 지원합니다. 아래 설명된 대로 두 엔드포인트 간에는 모델 접근 요구 사항이 다릅니다.

pip install -U 라인의 업그레이드에 주의하십시오. 2026년 10월 27일 기준으로 최신 SDK는 Bedrock을 포함하여 기본적으로 API 버전 2026-10-21을 전송합니다. Anthropic은 Claude Opus 4.6 및 이전 모델에 대해 나열된 ARN 버전 모델 ID가 Bedrock에서 해당 버전을 지원하지 않으며 400 오류를 반환할 수 있다고 문서화하고 있습니다. 서비스가 해당 모델 중 하나를 호출하는 경우 SDK를 현재 실행 중인 버전으로 유지하고 고정하거나, 먼저 서비스를 Claude 4.7 이상 모델로 이전하십시오.

여기서 리전은 단순한 장식이 아닙니다. Bedrock 엔드포인트는 리전별로 존재하며, 제공되는 Claude 모델도 리전마다 다릅니다. 또한 리전은 SigV4 서명의 일부이므로 한 리전에서 계산된 서명은 다른 리전에서 거부됩니다. SDK마다 리전이 생략되었을 때의 동작이 다르므로 서비스 환경에서 AWS_REGION을 명시적으로 설정하십시오. 2026년 10월에 문서화된 바와 같이, Python AnthropicBedrock 클라이언트는 AWS_REGION 또는 AWS_DEFAULT_REGION을 읽은 다음 boto3 세션 또는 AWS 프로필(~/.aws/config 포함)의 리전을 읽으며, 아무것도 확인되지 않으면 ValueError를 발생시킵니다. TypeScript 클라이언트는 AWS_REGION을 읽고, 설정되지 않은 경우 us-east-1로 대체하며, 리전을 위해 ~/.aws/config를 읽지 않습니다. 이것이 바로 AWS CLI는 동일한 장비에서 Claude 모델을 성공적으로 나열할 수 있는데 Node 프로세스는 잘못된 리전을 호출하는 이유입니다. CLI는 구성 파일을 읽었지만 클라이언트는 그렇지 않았기 때문입니다.

EC2 인스턴스에서는 IAM(Identity and Access Management) 역할을 연결하며 비밀 정보가 디스크에 저장되지 않습니다. 인스턴스 메타데이터 서비스가 SDK에 임시 자격 증명을 전달하기 때문입니다. AWS 외부의 VPS에는 인스턴스 역할이나 메타데이터 서비스가 없습니다. 이 경우 장비에 저장된 IAM 사용자의 장기 액세스 키 쌍(Anthropic 키와 동일한 등급의 비밀 정보)을 사용하거나 페더레이션을 선택해야 합니다. 페더레이션은 ID 공급자를 통해 인증하고 AWS STS(Security Token Service)를 호출한 뒤 반환된 임시 자격 증명을 사용하는 방식입니다. Bedrock은 AWS_BEARER_TOKEN_BEDROCK을 통해 전달되는 베어러 토큰인 Bedrock API 키도 허용하며, AWS는 두 가지 종류를 문서화하고 있습니다. 단기 키는 최대 12시간 또는 이를 생성한 세션 길이 중 짧은 시간 동안 지속되며, 생성한 IAM ID의 권한을 상속받습니다. AWS는 프로덕션 환경에 이 방식을 권장합니다. 장기 키는 생성 시 선택한 만료 시간(예: --credential-age-days을 사용하여 30일 또는 90일)까지 지속되거나, 해당 API 매개변수를 생략하면 만료되지 않습니다. 콘솔은 이 키 뒤에 IAM 사용자를 생성하며, AWS는 탐색 목적으로만 이 방식을 권장합니다. 장기 키는 생성된 리전에서만 작동하며 다른 리전에서 사용하면 Credential should be scoped to a valid region이 반환됩니다.

비용은 Anthropic이 아닌 AWS 계정으로 청구되며, 이것이 보통 이 서비스를 사용하는 주된 이유입니다. 2026년 10월 문서에 따르면 리전별 엔드포인트는 글로벌 엔드포인트보다 10%의 프리미엄이 부과됩니다. AWS의 Claude Platform은 별도의 제품입니다. Anthropic이 운영하고 AWS가 AWS Marketplace를 통해 청구하며, SigV4 또는 AWS 콘솔에서 생성된 API 키(Claude 콘솔에서 생성된 키는 작동하지 않음)로 인증합니다. 이는 Anthropic이 베타로 표시한 AnthropicAWS 클라이언트를 통해 이루어집니다. 권한 문제처럼 보이지만 실제로는 그렇지 않은 Bedrock 오류 하나를 알아둘 필요가 있습니다. Invocation of model ID ... with on-demand throughput isn't supported. Retry your request with the ID or ARN of an inference profile that contains this model. 이는 모델 라우팅 문제이며 자격 증명을 변경해도 해결되지 않습니다.

Route 3: Vertex AI에서 Google 자격 증명 사용

Anthropic의 문서에서는 이제 이 경로를 Google이 Agent Platform의 일부로 운영하는 Claude Models on Google Cloud (Google managed)라고 부른다. Agent Platform은 Google이 Vertex AI에서 발전시킨 서비스에 새로 붙인 이름이다. 아래에 표시된 aiplatform.googleapis.com 호스트, anthropic[vertex] 추가 항목, AnthropicVertex 클래스는 변경되지 않았다.

Google Cloud는 Application Default Credentials (ADC)를 사용한다. ADC는 자격 증명을 직접 지정하지 않아도 찾을 수 있도록 Google 인증 라이브러리가 따르는 고정 검색 순서다. ADC는 먼저 GOOGLE_APPLICATION_CREDENTIALS을 확인하고, 다음으로 gcloud auth application-default login가 작성한 파일을 확인한 뒤, metadata server를 통해 연결된 service account를 확인한다.

pip install -U "anthropic[vertex]"
gcloud auth application-default login

워크스테이션에서는 로그인할 때 $HOME/.config/gcloud/application_default_credentials.json가 작성되므로 작업이 끝난다. 서버에서는 사람 사용자의 자격 증명을 저장하지 않아야 한다. 이 명령은 service account impersonation도 지원한다. Google Cloud 외부에는 Google metadata server도 없으므로 GOOGLE_APPLICATION_CREDENTIALS을 사용해 ADC가 Workload Identity Federation 구성 파일 또는 service account key 파일을 가리키도록 해야 한다. service account key JSON 파일은 수명이 긴 secret이므로 이 가이드 뒷부분에 설명한 방식으로 정확히 관리해야 한다. Google Cloud 내부에서는 VM에 service account를 연결하면 보호할 파일이 없다. ADC가 찾는 identity에는 aiplatform.endpoints.predict permission이 포함된 IAM role이 필요하다. 예를 들면 Agent Platform User (roles/aiplatform.user)가 있다.

from anthropic import AnthropicVertex

client = AnthropicVertex(project_id="my-project", region="global")

SDK를 사용하지 않고 raw HTTP로 내려가면 2가지가 달라진다. model identifier는 request body에서 빠져 URL path로 이동하고, anthropic_version는 header에서 빠져 body로 이동한다. 2026년 10월 27일 기준으로 Anthropic 문서는 해당 위치에 vertex-2023-10-16 또는 더 새로운 API version인 2026-10-21을 사용할 수 있도록 허용한다. credential은 일반적인 Google access token이다. 아래 명령에서 gcloud auth print-access-token는 ADC가 아니라 gcloud CLI 자체의 로그인을 사용한다. 따라서 테스트하는 머신에서 먼저 gcloud auth login 또는 gcloud init를 실행해야 한다.

curl https://aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/global/publishers/anthropic/models/${MODEL_ID}:rawPredict \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{"anthropic_version": "vertex-2023-10-16", "max_tokens": 64, "messages": [{"role": "user", "content": "Hello"}]}'

Region은 핵심 인자다. global는 가용성을 위해 동적으로 라우팅하고, us과 eu은 multi-region identifier다. us-east5 같은 이름은 단일 region을 고정한다. 2026년 10월 기준으로 Anthropic은 Claude Sonnet 4.6 이하에 대해서만 single-region endpoint를 문서화한다. 최신 model은 global 또는 multi-region endpoint를 사용한다. 2026년 10월 문서에 따르면 multi-region 및 regional endpoint는 global보다 10% 더 비싸다. 결제는 Google Cloud project를 통해 처리되므로 quota와 invoice는 Google에서 관리한다.

2026년 10월 27일 기준으로 Anthropic은 두 번째 Google Cloud offering도 문서화하고 있으며, 이 offering의 request 형식은 다르다. Claude Models on Google Cloud (Anthropic managed)에서는 Anthropic이 직접 Claude API를 운영하며, AnthropicGoogleCloud client를 통해 claude.googleapis.com에 연결한다. 이 offering도 ADC를 포함한 Google Cloud credential로 인증하지만, request 형식은 direct API와 같다. model은 body에 그대로 남고 version은 anthropic-version header로 전달된다. 접근 권한은 자체 IAM role(roles/claude.user 및 관련 role)에서 부여한다. 설정 과정에서 project에 대한 새 Anthropic organization이 생성되며, 사용량은 Google Cloud Marketplace를 통해 청구된다. request URL에 aiplatform가 포함되고 :rawPredict로 끝난다면 이 절에서 설명하는 Google-managed 경로를 사용 중이다.

경로 4: Microsoft Foundry는 Azure 경로입니다

Azure에서 Claude를 검색했다면 이 섹션이 필요한 내용이며, 지원되는 경로가 실제로 존재합니다. Claude는 Microsoft Foundry(구 Azure AI Foundry)에서 실행되며, Claude Consumption Units 단위로 Azure Marketplace를 통해 청구됩니다. Foundry 리소스를 생성하고 그 안에 Claude 모델을 배포한 뒤, https://{resource}.services.ai.azure.com/anthropic/v1/*에 있는 Azure 호스팅 엔드포인트를 호출합니다.

두 가지 자격 증명을 사용할 수 있습니다. 첫 번째는 Foundry 포털의 배포 세부 정보 탭에서 제공하는 Azure 발급 키이며, api-key 또는 x-api-key 헤더로 전송합니다. 두 번째는 Microsoft Entra 토큰으로, 서버 환경에서는 Azure 역할 기반 접근 제어(RBAC)를 통해 엔드포인트 호출 권한을 관리할 수 있으므로 더 권장되는 방식입니다.

ACCESS_TOKEN=$(az account get-access-token --resource https://ai.azure.com --query accessToken -o tsv)

curl https://${RESOURCE}.services.ai.azure.com/anthropic/v1/messages \
  -H "content-type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -d '{"model": "DEPLOYMENT_NAME", "max_tokens": 64, "messages": [{"role": "user", "content": "Hello"}]}'

model 필드에는 모델 식별자가 아닌 배포 이름이 들어갑니다. 기본적으로는 두 값이 일치하지만, 사용자가 직접 배포 이름을 지정하는 순간 일치하지 않게 되며, 이는 정상적인 요청에서 Deployment not found 오류가 발생하는 가장 흔한 원인입니다. Python 및 TypeScript SDK는 환경 변수에서 ANTHROPIC_FOUNDRY_API_KEY 및 ANTHROPIC_FOUNDRY_RESOURCE를 읽어옵니다. 2026년 11월 10일 문서 기준으로 Foundry는 C#, Go, Java, PHP, Python, Ruby, TypeScript 등 7가지 공식 SDK를 모두 지원합니다. Go는 전용 foundry 패키지(go get github.com/anthropics/anthropic-sdk-go/v2/foundry)를 사용하며, Ruby는 2026년 11월 4일에 릴리스된 2.5.0 버전부터 전용 Anthropic::FoundryClient가 추가되었습니다. 해당 릴리스 이전에는 Ruby 코드에서 범용 클라이언트를 Foundry 기본 URL로 지정해야 했습니다.

범용 클라이언트를 Foundry 기본 URL로 지정하는 방식은 2.5.0 이전의 Ruby 코드든, Anthropic의 Foundry 예제에서 사용하는 ant CLI든 여전히 주의가 필요합니다. 범용 클라이언트에 자격 증명을 명시적으로 전달하지 않은 상태에서 환경 변수에 ANTHROPIC_API_KEY 또는 ANTHROPIC_AUTH_TOKEN가 설정되어 있으면, 클라이언트가 이를 가져와 Anthropic 자격 증명을 Microsoft 엔드포인트로 전송하게 됩니다. 해당 변수를 해제하거나, Foundry 키 또는 토큰을 클라이언트에 명시적으로 전달하십시오. Ruby의 경우 Foundry 키나 Entra 토큰 제공자를 받는 Anthropic::FoundryClient으로 전환하는 것이 더 깔끔한 해결책입니다. Entra 액세스 토큰은 60분에서 90분 사이의 임의의 기본 수명을 가지므로, 장시간 실행되는 프로세스는 시작 시점에 토큰을 획득하는 대신 주기적으로 갱신해야 합니다.

서버의 자격 증명은 얼마나 오래 유지됩니까?

차트Documented credential lifetime by route, hours
이 차트의 데이터
[
  {
    "label": "Anthropic key, 30-day preset",
    "max_lifetime_hours": 720
  },
  {
    "label": "Anthropic key, 7-day preset",
    "max_lifetime_hours": 168
  },
  {
    "label": "AWS STS assumed role",
    "max_lifetime_hours": 12
  },
  {
    "label": "Bedrock short-term API key",
    "max_lifetime_hours": 12
  },
  {
    "label": "Entra ID access token, default upper bound",
    "max_lifetime_hours": 1.5
  },
  {
    "label": "Federated Anthropic token, default",
    "max_lifetime_hours": 1
  }
]

이 수치들은 각 제공업체가 발표하고 2026년 10월 기준으로 확인된 상한선 및 기본값이며, 실제 측정값이 아닙니다. 이 정보가 중요한 이유는 단 한 가지입니다. 자격 증명이 유출되었음을 인지하는 동안 유출된 자격 증명이 얼마나 오랫동안 유효하게 작동하는지를 알려주기 때문입니다. 표 하단의 연합 Anthropic 토큰은 기본적으로 최대 1 시간 동안 유지되며, 이는 ID 제공업체 토큰의 잔여 수명의 2배라는 제한을 받습니다. Microsoft Entra 액세스 토큰에는 단일 기본값이 없습니다. Microsoft는 각 토큰에 60분에서 90분 사이(평균 75분)의 무작위 수명을 부여하며, 표에는 상한선인 1.5 시간으로 표시되어 있습니다. 이 기본값은 클라이언트, 리소스, 그리고 테넌트에서 조건부 액세스(Conditional Access) 활성화 여부에 따라 달라집니다. 클라이언트와 리소스가 모두 연속 액세스 평가(Continuous Access Evaluation)를 지원하는 경우, Entra는 수명을 24~28시간까지 연장할 수 있으며 계정 비활성화와 같은 이벤트 발생 시 실시간에 가깝게 토큰을 취소할 수 있습니다. 테넌트 토큰 수명 정책을 통해 10분에서 23:59:59 사이로 설정할 수 있습니다. SDK는 연합 Anthropic 토큰을 자동으로 갱신합니다. Foundry에서는 고정된 토큰 문자열을 전달하는 대신 Entra 토큰 제공업체를 구성하여 토큰을 갱신하십시오. 연합 규칙은 자체 토큰 수명을 1분에서 24시간 사이로 설정할 수 있으며, 콘솔의 Connect 워크로드 마법사는 10분을 기본값으로 채우므로 기본값을 가정하지 말고 규칙을 직접 확인하십시오. 가정된 역할(Assumed role)과 Bedrock 단기 API 키는 모두 12 시간으로 설정됩니다. Bedrock 장기 API 키는 고정된 상한선이 없으므로 표에 포함되지 않습니다. 이 키는 생성 시 선택한 만료일까지 유지되거나, API 호출 시 CredentialAgeDays을 생략한 경우 만료되지 않습니다. 이것이 바로 AWS가 해당 키를 탐색 목적으로만 사용할 것을 권장하는 이유입니다. 30일 사전 설정으로 생성된 키는 720 시간 동안 유효하며, 이것이 바로 서버의 파일에 한 달 동안 저장되는 자격 증명입니다.

VPS에서 자격 증명이 저장되는 위치

secret은 root만 읽을 수 있는 파일에 저장하고, systemd가 프로세스에 전달하게 합니다. 이 방식은 SDK 버전이 바뀌어도 그대로 적용되므로 한 번 제대로 구성할 가치가 있습니다.

sudo useradd --system --home /opt/claude-app --shell /usr/sbin/nologin claudeapp
sudo install -d -m 700 -o root -g root /etc/claude-app
sudo install -m 600 -o root -g root /dev/null /etc/claude-app/env
sudoedit /etc/claude-app/env

파일에는 일반적인 KEY=value 줄을 저장합니다. export도 없고 따옴표도 없으며 shell 문법도 사용하지 않습니다. systemd가 shell을 거치지 않고 직접 구문을 분석하기 때문입니다.

ANTHROPIC_API_KEY=sk-ant-api03-REPLACE-ME
CLAUDE_MODEL=REPLACE-ME
[Unit]
Description=Claude API service
After=network-online.target

[Service]
User=claudeapp
EnvironmentFile=/etc/claude-app/env
ExecStart=/opt/claude-app/venv/bin/python -m claude_app
Restart=on-failure

[Install]
WantedBy=multi-user.target

systemd는 root 권한으로 EnvironmentFile=을 읽은 다음 User=claudeapp 권한으로 낮춥니다. 따라서 서비스 계정에는 파일 읽기 권한이 필요하지 않습니다. root가 소유하고 mode 600으로 설정하면 충분하므로, 위의 install 명령이 이 설정을 적용합니다. sudo systemctl enable --now claude-app로 시작한 다음, systemctl status claude-app로 unit이 반복 재시작이 아니라 active (running) 상태에 도달했는지 확인합니다.

피해야 할 사항은 4가지입니다. 각각 확인 가능한 이유가 있습니다.

  • unit 파일 안에서 Environment=를 사용해 key를 작성하지 마십시오. /etc/systemd/system 아래의 unit은 모든 사용자가 읽을 수 있으므로 systemctl cat claude-app가 local 사용자에게 secret을 그대로 출력합니다.
  • commit하지 마십시오. .gitignore는 새 파일이 commit에 포함되지 않게 할 뿐, 이미 commit한 파일에는 아무 조치도 하지 않습니다. git history에는 입력된 내용이 그대로 남기 때문입니다.
  • container image에 포함하지 마십시오. ENV 값은 image 설정에 남고, build argument는 image history 또는 provenance metadata에서 볼 수 있습니다. 이후 layer에서 파일을 삭제해도 이전 layer에서는 제거되지 않습니다. 대신 --env-file 또는 mounted file을 사용해 실행 시점에 secret을 전달하십시오.
  • process environment가 root에게 비공개라고 생각하지 마십시오. sudo cat /proc/$(pgrep -u claudeapp -f claude_app | head -1)/environ | tr '\0' '\n'는 key를 그대로 출력합니다. 파일을 읽는 명령 자체에는 sudo가 필요합니다. shell input redirection은 sudo보다 먼저 실행되며 현재 계정의 권한을 사용합니다. 목적은 root가 아니라 시스템의 다른 모든 계정으로부터 secret을 보호하는 것입니다. root는 어떤 설정을 하더라도 secret을 읽을 수 있습니다.

이 마지막 내용은 이 설계가 제공하는 보호 범위를 보여 줍니다. root 전용 파일은 저장된 key를 보호하지만, 서비스 계정으로 실행되는 모든 code는 process environment를 읽을 수 있고 child process도 이를 상속합니다. 프로세스가 직접 작성하지 않은 code를 실행한다면 이 방식은 적절하지 않습니다. 프로세스가 실행할 수 있는 모든 것이 자신의 environment를 읽을 수 있기 때문입니다. AI agent가 secret에 접근하지 못하게 하기에서 이 경우를 설명합니다. 이는 다른 문제이며 해결 방법도 다릅니다.

키를 중단 없이 교체하려면 어떻게 해야 합니까?

새 키를 먼저 배포하고 마지막에 기존 키를 폐기합니다. 아래의 단일 서비스 재시작은 서비스를 잠시 중단합니다. 중단 없는 가용성을 유지하려면 재시작 중 요청을 처리할 다른 인스턴스가 필요합니다.

  1. 기존 키와 같은 workspace의 Console에서 새 키를 생성합니다.
  2. /etc/claude-app/env에 sudoedit을 사용해 기록합니다.
  3. sudo systemctl restart claude-app를 실행합니다.
  4. 서비스가 요청에 응답하는지 확인한 다음 Console에서 기존 키를 폐기합니다.

unit이 시작될 때 EnvironmentFile를 읽으므로 실행 중인 프로세스는 시작 시 전달받은 값을 계속 사용합니다. systemctl daemon-reload는 unit 파일을 다시 읽지만 실행 중인 프로세스의 환경에는 영향을 주지 않으므로, 새 키를 적용하려면 재시작해야 합니다. 1단계에서 4단계 대신 키를 폐기하면 3단계까지 서비스가 중단됩니다.

클라우드 경로의 키 교체는 provider에서 수행합니다. IAM user는 활성 access key를 동시에 2개까지 사용할 수 있으므로, 두 번째 키를 생성하고 배포한 다음 첫 번째 키를 삭제합니다. Google service account key도 같은 방식으로 교체합니다. Foundry resource에는 키가 2개 있으며, 한 키를 재생성하면 기존 값이 즉시 작동하지 않습니다. 따라서 사용 중인 키를 재생성하기 전에 다른 키로 서비스를 전환해야 합니다. Entra token과 federated Anthropic token은 수동으로 token을 교체할 필요가 없습니다. 가능한 경우 이를 사용하는 가장 강력한 이유가 바로 여기에 있습니다.

Console을 연 김에 workspace에 spend limit을 설정합니다. 유출된 키는 무엇보다 먼저 비용 문제를 일으킵니다. VPS에서 실행되는 agent가 사용할 수 있는 금액을 제한하는 방법에서 관련 제어 기능을 설명합니다.

client가 401 또는 403을 반환하는 이유는 무엇입니까?

직접 API에서 authentication_error와 함께 401이 반환됩니다. 키가 잘못되었거나 폐기되었거나 만료되었습니다. 만료는 특히 놓치기 쉽습니다. 코드가 변경되지 않았고 요청도 어제까지 작동했기 때문입니다. Console에서 키의 만료 열을 확인하거나 Admin API에서 expires_at를 읽으십시오. 만료가 설정되지 않은 키의 경우 그 값은 null입니다. 개인 키는 소유자가 organization을 떠나도 작동을 중지합니다.

SDK가 federation 설정을 무시하고 키를 사용합니다. ANTHROPIC_API_KEY와 ANTHROPIC_AUTH_TOKEN는 credential precedence 순서에서 federation보다 우선하므로 둘 중 하나가 federation 설정을 가립니다. 특히 환경 변수에 빈 문자열을 export해도 해당 슬롯은 비어 있지 않은 것으로 처리됩니다. 따라서 ANTHROPIC_API_KEY=""이면 SDK가 다음 단계로 넘어가지 않고 빈 키로 인증합니다. unset ANTHROPIC_API_KEY을 사용하십시오.

federation에서 Authentication failed라는 메시지만 표시되며 401이 반환됩니다. 이 메시지는 가능한 모든 원인에 대해 의도적으로 동일하게 표시됩니다. 따라서 호출자가 오류 텍스트를 읽고 rule 설정을 추측할 수 없습니다. 실제 원인은 Console의 authentication history 페이지에 기록됩니다. JWT를 추측하기보다 먼저 해당 페이지를 확인하십시오.

Foundry에서 403이 반환됩니다. token 인증은 성공했지만 Azure account에 해당 호출을 허용하는 role이 없습니다. 요청을 수행하는 identity에 Foundry User(이전 명칭 Azure AI User) 또는 Cognitive Services User 같은 Azure RBAC role을 할당하십시오.

Bedrock에서 어떤 오류든 발생합니다. SigV4 인증의 경우 먼저 service user로 aws sts get-caller-identity을 실행합니다. 이 명령은 해당 서버에 사용 가능한 AWS credential이 있는지 확인하므로, credential 문제와 model access 문제 또는 region 불일치를 구분할 수 있습니다. 2026년 10월 29일 기준으로 AWS는 필요한 AWS Marketplace permission이 있는 경우 commercial region에서 최초 사용 시 많은 model에 대한 access를 활성화합니다. 그러나 일부 model은 account 수준의 별도 access가 필요합니다. InvokeModel 경로로 호출하는 Anthropic model은 먼저 account별로 1회 use case form을 제출해야 합니다. 전체 AWS Organization에 대해 1회만 제출할 수도 있지만 opt-in region에서는 다시 제출해야 합니다. 승인이 완료될 때까지 호출은 AccessDeniedException를 반환합니다. AWS 문서에 따르면 이 form은 bedrock-mantle endpoint에는 적용되지 않습니다. account에서 특정 model을 처음 호출하면 Bedrock은 백그라운드에서 AWS Marketplace subscription을 시작합니다. 이 subscription에는 aws-marketplace:Subscribe, aws-marketplace:Unsubscribe 및 aws-marketplace:ViewSubscriptions permission을 보유한 identity가 필요합니다. permission이 없더라도 최초 호출이 반드시 실패하는 것은 아닙니다. AWS 문서에 따르면 subscription을 설정하는 동안 최대 15분까지 호출이 성공할 수 있으며, subscription이 실패하면 이후 호출은 같은 AccessDeniedException를 반환합니다. 처음 몇 분 동안 작동하다가 실패하기 시작한 서비스라면 credential보다 이 문제를 먼저 확인해야 합니다. permission을 부여한 뒤 AWS가 subscription을 완료하는 데 최대 2분이 걸릴 수 있습니다. 호출한 region에서 제공되지 않는 model은 credential이 아무리 올바르더라도 실패합니다.

FAQ

Claude를 Bedrock 또는 Vertex에서 사용하려면 Anthropic API key가 필요한가?

아니요. Amazon Bedrock에서는 SDK가 SigV4를 사용해 AWS credentials로 요청에 서명하거나 Bedrock API key를 전송합니다. Google Cloud에서는 Application Default Credentials를 통해 찾은 Google access token을 전송합니다. 두 구성 모두 Anthropic이 발급한 secret은 없으며, 사용량 요금은 Anthropic이 아니라 cloud account에 청구됩니다. 따라서 해당 호스트의 ANTHROPIC_API_KEY에 남아 있는 Anthropic key가 위험한 이유도 여기에 있습니다. cloud endpoint를 가리키도록 설정한 일반 client는 해당 key를 그대로 전송합니다.

Claude를 Azure에서 사용할 수 있는가?

예. 이전에 Azure AI Foundry라고 불렸던 Microsoft Foundry를 통해 사용할 수 있습니다. Foundry resource를 생성하고 Claude model을 배포한 다음, Azure가 발급한 key를 api-key header에 넣거나 Microsoft Entra bearer token을 사용해 https://{resource}.services.ai.azure.com/anthropic/v1/messages를 호출합니다. 사용량은 Claude Consumption Units 기준으로 Azure Marketplace를 통해 청구됩니다. 요청 body의 model field에는 deployment name을 넣어야 합니다. deployment를 생성할 때 기본 name을 유지한 경우에만 이 이름이 model identifier와 일치합니다. 이후에는 이름을 변경할 수 없습니다.

Linux server에서 Claude API key를 어디에 저장해야 하는가?

root가 소유하고 mode 600으로 설정한 file에 저장하고, systemd unit에서 EnvironmentFile=를 통해 불러옵니다. systemd는 unit의 User=로 전환하기 전에 root 권한으로 해당 file을 읽으므로 service account가 file에 접근할 필요가 없습니다. repository와 unit file 자체에는 저장하지 마십시오. unit file은 누구나 읽을 수 있으며 systemctl cat가 출력합니다. 또한 container image configuration, layer 및 build metadata에도 포함하지 마십시오.

아무것도 변경하지 않았는데 Claude API request가 401을 반환하기 시작한 이유는 무엇인가?

생성할 때 설정한 만료 시점에 도달한 key는 401을 반환합니다. 만료 시점은 생성할 때 설정되며 이후에는 수정할 수 없습니다. 단기 key는 경고 email 없이 만료됩니다. 만료된 key는 다시 활성화할 수 없으므로 replacement를 생성하고, 이를 environment file에 기록한 다음 service를 restart하고 기존 key를 나중에 revoke하십시오. key가 확실히 유효하다면 오래된 credential이 우선 적용되고 있지 않은지 확인하십시오. ANTHROPIC_API_KEY가 빈 문자열로 설정되어 있어도 아래의 federation 및 profile source보다 우선합니다.

이 글이 도움이 되었나요?

#claude#api#authentication#bedrock#vertex#secrets-management