가이드

작성자 Matt Connor 2026-08-20 · 업데이트됨 2026-08-21

Claude API 인증 4가지: key, Bedrock, Vertex, Foundry

Q: Claude를 Bedrock 또는 Vertex에서 사용하려면 Anthropic API key가 필요합니까?

아니요. Amazon Bedrock에서는 SDK가 SigV4를 사용해 AWS credentials로 각 요청에 서명합니다. Google Cloud에서는 Application Default Credentials를 통해 확인한 Google access token을 전송합니다. 두 방식 모두 Anthropic이 발급한 secret을 사용하지 않으며, 사용량은 Anthropic이 아니라 해당 cloud account에 청구됩니다. 따라서 이러한 호스트의 ANTHROPIC_API_KEY에 Anthropic key를 남겨 두면 위험합니다. cloud endpoint를 가리키도록 설정한 일반 client가 해당 key를 그대로 전송하기 때문입니다.

Q: Claude를 Azure에서 사용할 수 있습니까?

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

Q: 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 layer에도 저장하지 마십시오. docker history --no-trunc은 ENV 또는 --build-arg로 설정한 모든 값을 다시 출력합니다.

Q: 아무것도 변경하지 않았는데 Claude API 요청이 401을 반환하기 시작한 이유는 무엇입니까?

가장 흔한 원인은 key를 생성할 때 선택한 만료 시점에 도달한 것입니다. 만료 시점은 생성할 때 설정하며 이후에는 수정할 수 없습니다. 수명이 짧은 key는 경고 email 없이 만료됩니다. 만료된 key는 다시 활성화할 수 없으므로 replacement를 만들고, 이를 environment file에 기록한 다음 service를 재시작하고, 이후 기존 key를 revoke하십시오. key가 확실히 유효하다면 오래된 credential이 우선 적용되고 있지 않은지 확인하십시오. ANTHROPIC_API_KEY이 빈 문자열로 설정되어 있어도 다른 모든 credential source보다 우선합니다.

VPS의 Claude API client를 Anthropic key, AWS IAM, Google ADC, Entra로 인증하는 4가지 방법과 secret을 안전하게 저장하는 방법을 설명합니다.

Claude API 인증 경로 4가지

Claude API 인증은 클라이언트가 어떤 자격 증명을 네트워크로 전송하는지에 따라 결정된다. 선택지는 4가지이며, 하나의 메커니즘을 변형한 것이 아니다. 직접 Anthropic API를 사용하면 x-api-key 헤더에 정적 키를 보낸다. Amazon Bedrock은 AWS 자격 증명으로 모든 요청에 서명하며, 이 구성에는 Anthropic 키가 어디에도 존재하지 않는다. Google Cloud는 수명이 짧은 Google 액세스 토큰을 보낸다. Microsoft Foundry는 Azure에서 발급한 키 또는 Microsoft Entra 토큰을 사용한다.

이 가이드는 Linux 서버에서 실행 중인 서비스에 SDK(software development kit)를 연결하는 방법을 설명한다. 대신 Claude Code 명령줄 도구를 구성하는 경우 변수와 절차가 다르다. Claude Code를 Bedrock 또는 Vertex에 연결하기를 참고한다. 아직 서비스가 없다면 먼저 VPS에서 첫 Claude API 애플리케이션 만들기를 따라 구축한 다음, 이 가이드로 돌아와 자격 증명을 설정한다.

아래 내용은 2026년 8월 Anthropic의 플랫폼 문서를 기준으로 확인했다. 모델 식별자, 가격, SDK 버전, 엔드포인트 형식은 모두 변경될 수 있다. 따라서 이 가이드에서는 시간이 지나면 오래될 수 있는 값을 직접 싣지 않고 제공업체 페이지로 연결한다.

경로 1: Anthropic API key

이 경로는 직접 연결하는 방식이며, Anthropic이 secret을 발급하는 유일한 경로다. 요청은 Anthropic API host의 Messages endpoint로 전송하며, 모든 요청에 3개의 header가 포함된다.

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에서 현재 유효한 identifier로 바꾼다. 정상 응답은 content array와 usage object를 포함한 JSON이다. 잘못되었거나 만료된 key를 사용하면 authentication_error과 함께 HTTP 401이 반환된다. anthropic-version header가 없으면 별도의 오류가 발생한다. 이 header는 모든 요청에 필요하며 SDK가 자동으로 설정한다.

4가지 방법 중 client 생성 과정이 가장 짧다. 별도로 생성할 것이 없기 때문이다. 모든 공식 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)

key와 함께 model identifier도 환경 변수에 저장하는 것이 좋다. model name은 관리자가 통제할 수 없는 일정에 따라 변경된다. 문자열 하나를 수정하기 위해 코드를 다시 배포하는 작업은 피할 수 있다.

key는 Console에서 생성하며, 생성할 때 만료 기간을 선택한다. 3 hours, 1 day, 7 days 또는 30 days의 preset, custom duration, Never 중에서 선택할 수 있다. Expiry는 생성 시 고정되며 나중에 변경할 수 없다. Anthropic은 장기 key가 만료되기 전에 key 생성자에게 email을 보내지만, 수명이 짧은 key는 경고 email 없이 만료된다. 만료된 key는 401을 반환하며 다시 활성화할 수 없다. 따라서 해결 방법은 항상 새 key를 생성하는 것이다.

직접 API에서는 region을 선택할 수 없으며, 비용은 Anthropic organization에 직접 청구된다. Workspace를 사용하면 key를 하나의 project로 제한할 수 있다. 이는 단일 서비스의 비용을 확인하는 가장 명확한 방법이다. 해당 비용의 계산 방식은 token당 API pricing과 subscription 비교 방법을 참조한다.

여기서 한 가지 방법을 더 살펴볼 필요가 있다. 이 방법은 정적 secret을 완전히 제거한다. Workload Identity Federation을 사용하면 이미 신뢰하는 identity provider의 OpenID Connect (OIDC) token을 POST /v1/oauth/token에서 단기간 사용할 수 있는 Anthropic token으로 교환할 수 있으며, SDK가 token이 만료되기 전에 갱신한다. sk-ant-api... 문자열은 어디에서도 생성되거나 복사되지 않는다. 이 방식은 이미 platform identity를 제공하는 Kubernetes, GitHub Actions 및 cloud VM에 적합하다. 일반적인 VPS에는 이러한 issuer가 없는 경우가 많다. 따라서 해당 서버에서는 파일에 API key를 저장하는 것이 현실적인 방법이며, 이 가이드의 나머지 내용도 이를 전제로 한다.

Route 2: Amazon Bedrock에서 AWS 자격 증명

Bedrock에서는 Anthropic key를 전혀 보유하지 않습니다. SDK는 일반 AWS 자격 증명을 사용해 각 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)을 출력합니다. 다른 작업을 수행하기 전에 실행합니다. 이 명령이 실패하면 Claude 호출도 실패합니다. SDK가 동일한 자격 증명 탐색 순서를 사용하기 때문입니다. 먼저 생성자 인수를 확인하고, 다음으로 AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN 및 AWS_REGION 환경 변수를 확인한 뒤, AWS config 파일과 나머지 표준 탐색 경로(SSO, assumed roles, ECS task role, instance metadata service)를 확인합니다.

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

from anthropic import AnthropicBedrock

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

이 경우 Region은 단순한 장식이 아닙니다. Bedrock endpoint는 region별로 존재하고, 모델 액세스 권한은 AWS console에서 region별로 부여되며, region은 SigV4 서명에 포함됩니다. 따라서 한 region에서 계산한 서명은 다른 region에서 거부됩니다. 서비스 환경에서 AWS_REGION을 명시적으로 설정합니다. Anthropic 문서에 따르면 AnthropicBedrock client는 AWS_REGION을 읽고, 해당 값이 설정되지 않으면 us-east-1으로 대체합니다. 또한 region에 ~/.aws/config은 사용하지 않습니다. 따라서 같은 서버에서 AWS CLI로는 Claude 모델을 성공적으로 나열할 수 있지만 Python 프로세스에서는 실패할 수 있습니다. CLI는 config 파일을 읽지만 client는 읽지 않기 때문입니다.

EC2 인스턴스에는 IAM (identity and access management) role을 연결할 수 있으며, instance metadata service가 SDK에 임시 자격 증명을 전달하므로 secret이 디스크에 저장되지 않습니다. AWS 외부의 VPS에는 instance role도 metadata service도 없습니다. 이 경우 장기간 유효한 IAM user access key pair를 서버에 저장할지, 아니면 federation을 사용할지 선택해야 합니다. 전자는 Anthropic key와 동일한 유형의 secret입니다. federation을 사용하면 identity provider를 통해 인증하고, AWS STS (security token service)를 호출한 다음, STS가 반환하는 임시 자격 증명을 사용합니다. Bedrock은 AWS_BEARER_TOKEN_BEDROCK을 통한 bearer token도 허용합니다. 이 방식은 문서상 최대 유효 기간이 12 hours이며, AWS는 이를 가장 권장하지 않는 방식으로 설명합니다.

청구서는 Anthropic이 아니라 AWS account로 발행됩니다. 보통 이것이 Bedrock을 사용하는 주된 이유입니다. 2026년 8월 문서에 따르면 regional endpoint에는 global endpoint보다 10%의 추가 요금이 부과됩니다. 권한 문제처럼 보이지만 실제로는 권한 문제가 아닌 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. 이는 model routing 문제이며, 자격 증명을 변경해도 해결되지 않습니다.

경로 3: Vertex AI에서 Google 인증 정보 사용

Google Cloud는 Application Default Credentials(ADC)를 사용합니다. ADC는 Google 인증 라이브러리가 인증 정보를 지정하지 않아도 찾을 때 따르는 고정된 검색 순서입니다. ADC는 먼저 GOOGLE_APPLICATION_CREDENTIALS을 확인한 다음 gcloud auth application-default login가 작성한 파일을 확인하고, 마지막으로 메타데이터 서버를 통해 연결된 서비스 계정을 확인합니다.

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

워크스테이션에서는 login을 실행하면 $HOME/.config/gcloud/application_default_credentials.json가 작성되므로 작업이 끝납니다. 서버에서는 잘못된 도구입니다. 저장되는 인증 정보가 사람에게 속하며 해당 사용자의 계정이 삭제되면 함께 사용할 수 없기 때문입니다. Google Cloud 외부에는 메타데이터 서버도 없으므로 ADC는 GOOGLE_APPLICATION_CREDENTIALS로 넘어가 서비스 계정 키 파일을 가리키게 됩니다. 이 JSON 파일은 장기간 유효한 비밀이며, 이 가이드 뒤에서 설명하는 방식으로 정확하게 관리해야 합니다. Google Cloud 내부에서는 VM에 서비스 계정을 연결하면 보호해야 할 파일이 없습니다.

from anthropic import AnthropicVertex

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

SDK를 사용하지 않고 raw HTTP로 내려가면 2가지가 달라집니다. 모델 식별자는 요청 본문에서 URL 경로로 이동하고, anthropic_version은 헤더에서 본문으로 이동하며 본문에서는 vertex-2023-10-16로 읽어야 합니다. 인증 정보는 일반적인 Google 액세스 토큰입니다.

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"}]}'

리전은 독립적인 주요 인수입니다. global은 가용성을 기준으로 동적으로 라우팅하고, us과 eu은 멀티 리전 식별자이며, us-east5와 같은 이름은 단일 리전으로 고정합니다. 2026년 8월에 문서화된 내용에 따르면 멀티 리전 및 리전 엔드포인트의 비용은 global보다 10% 높습니다. 결제는 Google Cloud 프로젝트를 통해 처리되므로 할당량과 청구서는 Google에서 관리합니다.

Route 4: Microsoft Foundry는 Azure 경로다

Azure에서 Claude를 검색했다면 이 절에서 원하는 내용을 찾을 수 있다. 지원되는 경로가 실제로 존재한다. Claude는 Microsoft Foundry(이전 명칭: Azure AI Foundry)에서 실행되며, Azure Marketplace를 통해 Claude Consumption Units로 과금된다. Foundry 리소스를 생성하고, 그 안에 Claude 모델을 배포한 다음, https://{resource}.services.ai.azure.com/anthropic/v1/*의 Azure 호스팅 엔드포인트를 호출한다.

사용할 수 있는 자격 증명은 2가지다. 첫 번째는 Foundry 포털의 배포 Details 탭에서 발급되는 Azure 키다. 이 키는 api-key 또는 x-api-key 헤더로 전송한다. 두 번째는 Microsoft Entra 토큰이다. 서버에서는 Azure 역할 기반 액세스 제어로 엔드포인트를 호출할 수 있는 사용자를 관리할 수 있으므로 이 방식을 사용하는 편이 좋다.

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를 읽는다. 모든 SDK가 Foundry를 지원하는 것은 아니다. 2026년 8월 기준으로 지원되는 SDK는 C#, Java, PHP, Python 및 TypeScript다. Go 및 Ruby SDK에서는 일반 클라이언트가 Foundry 기본 URL을 사용하도록 지정해야 한다.

이 우회 방법에는 주의할 점이 있다. 환경에 ANTHROPIC_API_KEY가 계속 설정되어 있으면 일반 클라이언트가 이 값을 읽고 Anthropic 키를 Microsoft 엔드포인트로 전송한다. 이 변수를 설정 해제하거나 클라이언트에서 환경 변수 기본값 사용을 비활성화한다. Entra 토큰은 약 1시간 후 만료된다. 따라서 장시간 실행되는 프로세스는 시작할 때 토큰을 한 번만 읽어 두지 말고 토큰을 갱신해야 한다.

서버의 자격 증명은 얼마 동안 유효한가?

ChartDocumented maximum credential lifetime by route, hours

label

max_lifetime_hours

Anthropic key, 30-day preset

720

Anthropic key, 7-day preset

168

AWS STS assumed role

Bedrock bearer token

Entra ID access token

Federated Anthropic token

The data behind this chart

[
  {
    "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 bearer token",
    "max_lifetime_hours": 12
  },
  {
    "label": "Entra ID access token",
    "max_lifetime_hours": 1
  },
  {
    "label": "Federated Anthropic token",
    "max_lifetime_hours": 1
  }
]

이는 각 제공업체가 공개한 최대값과 기본값을 2026년 8월에 확인한 것이며, 측정값이 아니다. 이 수치가 중요한 이유는 하나다. 자격 증명이 유출된 사실을 아직 파악하는 동안에도 유출된 자격 증명이 얼마 동안 계속 작동하는지 보여 주기 때문이다. 차트 하단의 단기 토큰은 각각 1시간 동안 유효하며 SDK가 이를 갱신하므로, 짧은 유효 기간이 운영에 부담을 주지 않는다. AssumeRole로 얻은 자격 증명은 12시간 동안 유효하다. 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도 사용하지 않고, 따옴표도 사용하지 않으며, 셸 구문도 사용하지 않는다. systemd가 셸을 통해 실행하지 않고 직접 파싱하기 때문이다.

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는 EnvironmentFile=을 root 권한으로 읽은 뒤 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이 secret을 모든 로컬 사용자에게 출력한다.
commit하지 않는다. .gitignore은 새 파일이 commit에 포함되지 않게 할 뿐, 이미 commit된 파일에는 아무런 조치도 하지 않는다. git history에는 입력된 내용이 그대로 남기 때문이다.
container image에 포함하지 않는다. ENV 줄과 --build-arg 값은 image layer에 기록되며, docker history --no-trunc이 이를 다시 출력한다. 이후 layer에서 파일을 삭제해도 이전 layer에서는 삭제되지 않는다. 대신 --env-file을 사용하거나 파일을 mount해 실행 시점에 secret을 전달한다.
프로세스 환경이 root에게도 private하다고 생각하지 않는다. sudo tr '\\0' '\\n' < /proc/$(pgrep -u claudeapp -f claude_app | head -1)/environ이 key를 다시 출력한다. 목표는 장비의 다른 모든 계정으로부터 secret을 차단하는 것이지, 어떤 방법을 사용해도 읽을 수 있는 root로부터 차단하는 것이 아니다.

마지막 항목은 이 설계가 제공하는 보호 범위를 보여준다. secret을 읽을 수 있는 주체가 서비스와 root뿐이라면 environment variable은 secret을 담는 적절한 container다. 그러나 프로세스가 직접 작성하지 않은 code를 실행한다면 적절하지 않다. 프로세스가 실행할 수 있는 모든 code는 자신의 environment를 읽을 수 있기 때문이다. AI agent가 secret에 접근하지 못하게 하기에서는 이 경우를 다룬다. 이는 다른 문제이며, 해결 방법도 다르다.

다운타임 없이 키를 어떻게 교체합니까?

새 키를 먼저 적용하고 기존 키는 마지막에 폐기합니다.

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

unit이 시작될 때 EnvironmentFile을 읽으므로 실행 중인 프로세스는 시작 시 전달받은 값을 계속 사용합니다. systemctl daemon-reload는 unit 파일을 다시 읽지만 실행 중인 프로세스의 환경은 변경하지 않습니다. 따라서 새 키를 적용하려면 재시작해야 합니다. 1단계에서 기존 키를 폐기하고 4단계까지 진행하면 그만큼 다운타임이 발생합니다.

나머지 3가지 방식은 provider에서 키를 교체합니다. IAM 사용자는 활성 access key를 2개까지 동시에 사용할 수 있으므로 두 번째 키를 생성하고 배포한 다음 첫 번째 키를 삭제합니다. Google service account 키도 같은 방식으로 교체합니다. Foundry 키는 portal에서 재생성하며 기존 키가 즉시 무효화됩니다. 따라서 클릭하기 전에 새 값을 기록해야 합니다. Entra 토큰과 federated Anthropic 토큰은 아예 교체할 필요가 없습니다. 가능한 경우 이 토큰을 사용하는 가장 강력한 이유입니다.

Console에 있는 동안 workspace에 spend limit을 설정합니다. 키가 유출되면 다른 어떤 문제보다 먼저 비용이 발생합니다. VPS에서 실행되는 에이전트의 지출 한도 설정에서 관련 제어 방법을 설명합니다.

클라이언트가 401 또는 403을 반환하는 이유는 무엇인가?

직접 API에서 authentication_error와 함께 401이 반환되는 경우. 키가 잘못되었거나 폐기되었거나 만료되었다. 만료는 코드가 변경되지 않았고 요청이 어제까지 정상적으로 동작했기 때문에 놓치기 쉽다. Console에서 키의 만료 열을 확인하거나 Admin API에서 expires_at를 조회한다. 만료가 설정되지 않은 키에서는 이 값이 null이다.

SDK가 federation 설정을 무시하고 키를 사용하는 경우. ANTHROPIC_API_KEY과 ANTHROPIC_AUTH_TOKEN은 자격 증명 우선순위에서 federation보다 앞에 있으므로 federation 설정을 가린다. 특히 환경 변수에 빈 문자열을 내보내도 해당 우선순위 슬롯은 비어 있지 않은 것으로 처리된다. 따라서 ANTHROPIC_API_KEY=""은 SDK가 다음 자격 증명으로 넘어가지 않고 빈 키로 인증하게 만든다. unset ANTHROPIC_API_KEY를 사용한다.

federation에서 Authentication failed이라는 메시지만 표시되며 401이 반환되는 경우. 이 메시지는 가능한 모든 원인에 대해 의도적으로 동일하게 표시된다. 따라서 호출자가 오류 문구를 읽고 규칙 설정을 추측할 수 없다. 실제 원인은 Console의 인증 기록 페이지에 기록된다. JWT를 추측하기보다 해당 페이지부터 확인한다.

Foundry에서 403이 반환되는 경우. 토큰 인증에는 성공했지만 Azure 계정에 해당 호출을 허용하는 역할이 없다. 요청을 수행하는 ID에 Foundry User (formerly Azure AI User) 또는 Cognitive Services User와 같은 Azure RBAC 역할을 할당한다.

Bedrock에서 어떤 오류든 발생하는 경우. 먼저 서비스 사용자로 aws sts get-caller-identity을 실행한다. 이 명령은 해당 호스트에 사용 가능한 AWS 자격 증명이 있는지 확인한다. 이를 통해 자격 증명 문제인지, 모델 액세스 문제인지, 리전 불일치인지 구분할 수 있다. 모델 액세스 권한은 AWS console에서 리전별로 부여되므로, 한 리전에서 활성화한 뒤 다른 리전을 대상으로 호출하기 쉽다.

FAQ

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

아니요. Amazon Bedrock에서는 SDK가 SigV4를 사용해 AWS credentials로 각 요청에 서명합니다. 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을 배포한 다음, https://{resource}.services.ai.azure.com/anthropic/v1/messages을 호출합니다. 이때 api-key header에 Azure가 발급한 key를 넣거나 Microsoft Entra bearer token을 사용할 수 있습니다. 사용량은 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 layer에도 저장하지 마십시오. docker history --no-trunc은 ENV 또는 --build-arg로 설정한 모든 값을 다시 출력합니다.

아무것도 변경하지 않았는데 Claude API 요청이 401을 반환하기 시작한 이유는 무엇입니까?

가장 흔한 원인은 key를 생성할 때 선택한 만료 시점에 도달한 것입니다. 만료 시점은 생성할 때 설정하며 이후에는 수정할 수 없습니다. 수명이 짧은 key는 경고 email 없이 만료됩니다. 만료된 key는 다시 활성화할 수 없으므로 replacement를 만들고, 이를 environment file에 기록한 다음 service를 재시작하고, 이후 기존 key를 revoke하십시오. key가 확실히 유효하다면 오래된 credential이 우선 적용되고 있지 않은지 확인하십시오. ANTHROPIC_API_KEY이 빈 문자열로 설정되어 있어도 다른 모든 credential source보다 우선합니다.

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