---
title: Claude Platform on AWS
url: https://platform.claude.com/docs/ko/build-with-claude/claude-platform-on-aws
description: Anthropic이 관리하는 인프라를 통해 AWS에서 Claude의 전체 플랫폼 기능에 액세스하세요.
---
Claude Platform on AWS는 Messages API, Agent Skills, 코드 실행, 베타 기능을 포함한 Anthropic 플랫폼의 전체 경험을 AWS 계정을 통해 제공합니다. AWS가 추론 스택을 운영하는 [Amazon Bedrock](https://platform.claude.com/docs/ko/build-with-claude/claude-in-amazon-bedrock)과 달리, Claude Platform on AWS는 Anthropic이 운영합니다. AWS는 인증 계층(SigV4 또는 API 키), IAM 기반 액세스 제어, AWS Marketplace를 통한 결제 통합을 제공합니다.
Anthropic SDK는 Claude Platform on AWS를 지원합니다.
## 플랫폼 통합 작동 방식
Claude 모델은 Anthropic이 관리하는 인프라에서 실행됩니다. 이는 AWS를 통한 결제 및 액세스를 위한 상업적 통합입니다. Anthropic은 추론 입력 및 출력에 대한 데이터 처리자입니다. AWS는 마켓플레이스 모델에 따라 결제 및 ID 메타데이터를 처리합니다. Claude Platform on AWS를 통해 Claude를 사용하는 고객에게는 Anthropic의 [데이터 사용 약관](https://www.anthropic.com/legal)이 적용됩니다.
Anthropic은 AWS 인프라를 사용하여 API 요청을 처리하고, 모델 추론을 실행하며, 워크스페이스 콘텐츠(프롬프트, 출력, 파일, Skills, 배치 등)를 저장합니다. 2026년 9월 18일 00:00 UTC 이전에 생성된 워크스페이스의 경우, Anthropic은 AWS 외부에서 요청을 처리하고, 데이터를 저장하고, 추론을 실행할 수 있습니다. 어느 경우든 하위 서비스는 예고 없이 변경될 수 있습니다. 추론을 특정 지역으로 고정하려면 요청별로 [`inference_geo`](https://platform.claude.com/docs/ko/build-with-claude/claude-platform-on-aws#data-residency) 매개변수를 설정하세요.
Claude Platform on AWS는 퍼스트 파티 Claude API와 동일한 데이터 보존 정책을 따릅니다. "Zero Data Retention"(데이터 무보존), 즉 ZDR은 요청 시 사용할 수 있습니다. 조직에서 이를 활성화하려면 Anthropic 계정 담당자에게 문의하세요.
## Claude Platform on AWS와 Amazon Bedrock 비교
두 서비스 모두 AWS를 통해 Claude를 사용할 수 있게 해 주지만, 아키텍처, API 표면, 기능 가용성에서 차이가 있습니다.
| 항목 | Claude Platform on AWS | [Claude in Amazon Bedrock](https://platform.claude.com/docs/ko/build-with-claude/claude-in-amazon-bedrock) | [Amazon Bedrock (Opus 4.6 이하)](https://platform.claude.com/docs/ko/build-with-claude/claude-on-amazon-bedrock-legacy) |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| **스택 운영 주체** | Anthropic | AWS | AWS |
| **API 표면** | Claude API (`/v1/{endpoint}`) | `/anthropic/v1/messages`의 Messages API | Bedrock Converse / InvokeModel |
| **기능 가용성** | 일반적으로 Claude API와 같은 날 제공([기능 제한 사항](https://platform.claude.com/docs/ko/build-with-claude/claude-platform-on-aws#features-not-supported) 참조) | Amazon Bedrock 출시 일정에 따름 | Amazon Bedrock 출시 일정에 따름 |
| **Agent Skills** | 사용 가능 | 사용 불가(코드 실행 필요) | 사용 불가 |
| **베타 기능** | `anthropic-beta` 헤더로 전달([기능 제한 사항](https://platform.claude.com/docs/ko/build-with-claude/claude-platform-on-aws#features-not-supported) 참조) | Amazon Bedrock이 지원하는 베타 기능을 `anthropic-beta` 헤더를 통해 사용 | Amazon Bedrock이 지원하는 베타 기능을 InvokeModel 요청 본문의 `anthropic_beta` 필드를 통해 사용 |
| **인증** | AWS IAM / SigV4 또는 API 키 | AWS IAM / SigV4 | AWS IAM / SigV4 또는 bearer 토큰 |
| **결제** | AWS Marketplace | AWS(네이티브 서비스) | AWS(네이티브 서비스) |
| **기본 URL** | `aws-external-anthropic.{region}.api.aws` | `bedrock-mantle.{region}.api.aws` | `bedrock-runtime.{region}.amazonaws.com` |
| **SDK 클라이언트** | `AnthropicAWS` (typescript: `AnthropicAws`; csharp: `AnthropicAwsClient`; go: `anthropicaws.NewClient()`; java: `AwsBackend`; php: `Anthropic\Aws\Client`; ruby: `Anthropic::AWSClient`), 베타 | `AnthropicBedrockMantle` | `AnthropicBedrock` / Bedrock SDK |
| **콘솔** | Claude Console(`platform.claude.com`, AWS Console을 통해 액세스) | Bedrock Console | Bedrock Console |
| **속도 제한 및 할당량** | Anthropic이 관리 | AWS가 관리 | AWS가 관리 |
| **추론 데이터 처리자** | Anthropic | AWS | AWS |
AWS가 운영하는 Claude가 필요하다면 [Claude in Amazon Bedrock](https://platform.claude.com/docs/ko/build-with-claude/claude-in-amazon-bedrock)을 참조하세요. Claude Platform on AWS는 퍼스트 파티 Claude API 및 Amazon Bedrock과 별도의 용량 풀을 사용합니다. 둘 이상의 플랫폼에서 워크로드를 실행하고 플랫폼 간에 장애 조치(failover)할 수 있습니다.
VPC를 Claude Platform on AWS 엔드포인트에 연결하기 위해 [AWS PrivateLink](https://docs.aws.amazon.com/vpc/latest/privatelink/what-is-privatelink.html)가 지원됩니다.
**Bedrock을 선택해야 하는 경우:** FedRAMP High, IL4, IL5 또는 HIPAA 대응 규정 준수가 필요하거나 AWS가 유일한 데이터 처리자여야 하는 규제 산업의 조직은 [Claude in Amazon Bedrock](https://platform.claude.com/docs/ko/build-with-claude/claude-in-amazon-bedrock)을 사용해야 합니다. Bedrock은 AWS가 운영 주체로서 전적으로 AWS가 제어하는 인프라에서 실행됩니다.
**어떤 서비스를 사용하고 계신가요?** Claude는 여러 개별 제품을 통해 제공됩니다:
* **Claude Platform on AWS**(이 페이지): AWS Marketplace를 통해 결제되는 Claude API 플랫폼입니다. [Claude Console](https://platform.claude.com/docs/ko/build-with-claude/claude-platform-on-aws#using-the-claude-console)과 AWS Console에서 관리합니다.
* **[Claude in Amazon Bedrock](https://platform.claude.com/docs/ko/build-with-claude/claude-in-amazon-bedrock):** AWS 네이티브 서비스입니다. Amazon Bedrock 콘솔에서 관리하며 AWS 서비스 사용량으로 결제됩니다.
* **AWS Marketplace를 통해 조달한 Claude Enterprise:** API 플랫폼이 아닌 [claude.ai](https://claude.ai) 플랜(Claude 채팅 제품)입니다. claude.ai에서 관리하며, 계정 및 마이그레이션 동작이 이 페이지에서 설명하는 내용과 다릅니다. [Claude 고객센터](https://support.claude.com)를 참조하세요.
* **Anthropic 직접 계정:** Anthropic이 결제하는 퍼스트 파티 Claude API 및 claude.ai 플랜입니다. Claude Console과 claude.ai에서 관리합니다.
## 계정 설정
Claude Platform on AWS 설정은 네 단계로 진행됩니다: AWS Console 서비스 페이지에서 가입하고, Anthropic 조직 설정을 완료하고, 워크스페이스 ID를 확인하고, Claude Console에 로그인합니다.
AWS Console을 통해 가입하면 AWS 계정에 연결된 새 Anthropic 조직이 프로비저닝됩니다. 이 조직은 AWS Marketplace를 통해 조달한 Claude Enterprise 조직을 포함하여 회사가 Anthropic과 보유한 기존 조직과 별개입니다. 퍼스트 파티 Anthropic 조직의 API 키, 워크스페이스, Claude Console 설정은 이전되지 않습니다.
기존 Amazon Bedrock 비공개 오퍼(private offer)가 있는 경우, 첫 요청부터 할인이 적용되도록 가입 전에 Anthropic 또는 AWS 계정 담당자에게 문의하세요. 비공개 오퍼가 수락되기 전에 발생한 사용량에는 할인을 소급 적용할 수 없습니다. [비공개 오퍼](https://platform.claude.com/docs/ko/about-claude/pricing#private-offers)를 참조하세요.
1. [AWS Console](https://console.aws.amazon.com/)을 열고 **Claude Platform on AWS** 서비스 페이지로 이동합니다.
2. **Sign up**을 선택합니다.
3. 가입 페이지에서 약관(Anthropic의 최종 사용자 라이선스 계약, AWS 개인정보 보호 고지, AWS 고객 계약)을 검토하고 동의 체크박스를 선택합니다.
4. **Continue**를 선택합니다.
페이지에 **Sign-up in progress** 배너가 표시됩니다. 페이지를 벗어나지 마세요. AWS가 AWS Marketplace 구독을 대신 처리하는 동안 가입에 몇 분이 걸리며, 이후 자동으로 리디렉션됩니다.
조직에 Anthropic의 비공개 오퍼가 있는 경우, Console이 이를 조회하여 AWS Marketplace에서 수락하라는 메시지를 표시합니다. 자세한 내용은 [비공개 오퍼](https://platform.claude.com/docs/ko/about-claude/pricing#private-offers)를 참조하세요.
Claude Platform on AWS를 사용하면 Anthropic은 AWS 인프라에서 콘텐츠(프롬프트 및 출력 등)를 처리하고 저장합니다. 2026년 9월 18일 00:00 UTC 이전에 생성된 워크스페이스의 경우, Anthropic은 해당 콘텐츠를 AWS 외부에서 처리하고 저장할 수 있습니다. Anthropic의 [데이터 사용 정책](https://www.anthropic.com/legal)에서 콘텐츠와 메타데이터가 처리 및 저장되는 방식을 설명합니다.
가입이 완료되면 `platform.claude.com/partner-signup`으로 리디렉션됩니다.
1. 조직 소유자의 이메일 주소를 입력하고 **Get started**를 선택합니다.
2. 해당 이메일 받은편지함에서 설정 링크를 확인하고 따라갑니다. 브라우저에 **Signed in as a different account** 페이지가 표시되면 **Log out and continue**를 선택합니다.
3. 조직 세부 정보 양식(조직 이름, 법인 유형, 국가, 사용 목적)을 작성하고 **Complete setup**을 선택합니다.
설정을 완료하면 Anthropic 조직이 생성되고 Anthropic의 상업 서비스 약관 및 사용 정책에 동의하게 됩니다. 이제 AWS Console 서비스 페이지에 **Home**, **API keys**, **Quickstart**, **Workspaces**가 있는 왼쪽 탐색 메뉴가 표시됩니다.
설정을 완료하면 AWS Console에서 워크스페이스를 생성하라는 메시지가 표시됩니다. 리전 바인딩, IAM 리소스 범위 지정, 추가 워크스페이스 생성에 대한 자세한 내용은 [워크스페이스](https://platform.claude.com/docs/ko/build-with-claude/claude-platform-on-aws#workspaces)를 참조하세요.
워크스페이스 ID는 AWS Console **Claude Platform on AWS** 서비스 페이지의 **Workspaces** 아래 또는 [Claude Console](https://platform.claude.com/docs/ko/build-with-claude/claude-platform-on-aws#using-the-claude-console)에서 찾을 수 있습니다. 워크스페이스 ID는 `wrkspc_` 뒤에 영숫자 식별자가 붙는 형식을 사용합니다.
Claude Console에 대한 액세스는 AWS IAM을 통해 페더레이션됩니다:
1. `aws-external-anthropic:AssumeConsole` 권한이 있는 IAM 역할을 수임합니다. [Claude Platform on AWS용 IAM 작업](https://platform.claude.com/docs/ko/api/claude-platform-on-aws-iam-actions#console-access)을 참조하세요.
2. **Claude Platform on AWS** 서비스 페이지에서 **Open Claude Console**을 선택합니다. AWS Console이 JWT를 발급하고 `platform.claude.com`으로 리디렉션합니다.
3. 처음 로그인할 때 이메일 주소를 입력하라는 메시지가 표시됩니다. 업무용 이메일을 입력하세요. 플랫폼이 Claude Console 사용자를 즉시(just-in-time) 프로비저닝합니다.
AWS Console을 통해 로그인하면 Claude Console의 범위가 Claude Platform on AWS 조직으로 지정됩니다. Claude Console 사이드바 왼쪽 하단에 **Account managed by AWS** 표시가 나타납니다.
### 기존 Anthropic 조직에서 이전하기
Claude Platform on AWS에 가입하면 항상 AWS 계정에 연결된 새 Anthropic 조직이 프로비저닝됩니다. 제자리 전환은 없습니다: 퍼스트 파티 Claude API 조직과 같은 기존 조직은 Claude Platform on AWS 조직이 될 수 없습니다.
기존 조직에서의 이전은 새 조직으로의 전환(cutover)으로 계획하세요:
* **새 조직을 먼저 생성하세요.** AWS Console을 통해 가입합니다([계정 설정](https://platform.claude.com/docs/ko/build-with-claude/claude-platform-on-aws#set-up-your-account) 참조). 이전에 비공개 오퍼가 포함된 경우, 오퍼가 수락되기 전에 가입을 완료하세요: 할인은 수락 시점부터 적용되며 소급 적용되지 않습니다. [비공개 오퍼](https://platform.claude.com/docs/ko/about-claude/pricing#private-offers)를 참조하세요.
* **액세스 및 구성을 다시 만드세요.** API 키, 워크스페이스, Claude Console 설정은 기존 조직에서 이전되지 않습니다. 새 조직에서 워크스페이스를 생성하고 애플리케이션을 [Claude Platform on AWS 인증](https://platform.claude.com/docs/ko/build-with-claude/claude-platform-on-aws#authentication)으로 전환하세요.
* **통합을 업데이트하세요.** Claude Platform on AWS는 Claude API(`/v1/{endpoint}`)를 제공하므로 요청 및 응답 형태는 퍼스트 파티 Claude API와 동일합니다. 변경되는 것은 기본 URL, 인증 방법, 그리고 추론 및 리소스 요청의 `anthropic-workspace-id` 헤더입니다. [요청 보내기](https://platform.claude.com/docs/ko/build-with-claude/claude-platform-on-aws#making-requests)를 참조하세요. 일부 플랫폼 기능은 다릅니다. [지원되지 않는 기능](https://platform.claude.com/docs/ko/build-with-claude/claude-platform-on-aws#features-not-supported)을 참조하세요.
* **원하는 일정에 따라 전환하세요.** 새 조직은 기존 조직과 독립적이며, 두 조직 모두 병렬로 트래픽을 처리할 수 있습니다. 일괄 전환할 필요가 없습니다: 모든 트래픽이 새 조직으로 옮겨질 때까지 워크로드를 점진적으로 이동하세요.
새 조직이 운영되기 시작하면, 차이점은 AWS를 통해 처리되는 결제와 인증에 집중됩니다:
* **결제**는 AWS Marketplace로 이동합니다: 사용량은 선불 크레딧이 아닌 Claude Consumption Units로 청구되며([결제](https://platform.claude.com/docs/ko/build-with-claude/claude-platform-on-aws#billing) 참조), Billing 페이지에서 지출 한도를 설정합니다([지출 한도](https://platform.claude.com/docs/ko/build-with-claude/claude-platform-on-aws#spend-limits) 참조). 전환 기간 동안 결제는 별도로 유지됩니다: 기존 조직은 현재와 같이 계속 청구됩니다.
* **인증 및 액세스**는 AWS로 이동합니다: 요청은 AWS 자격 증명 또는 Claude Console이 아닌 AWS Console에서 생성한 API 키로 인증합니다([인증](https://platform.claude.com/docs/ko/build-with-claude/claude-platform-on-aws#authentication) 참조). 조직 멤버십은 Claude Console이 아닌 AWS IAM을 통해 관리되며([사용 가능한 페이지](https://platform.claude.com/docs/ko/build-with-claude/claude-platform-on-aws#available-pages) 참조), Anthropic의 클라이언트 SDK는 플랫폼별 클라이언트 클래스를 제공합니다([SDK 설치](https://platform.claude.com/docs/ko/build-with-claude/claude-platform-on-aws#install-an-sdk) 참조).
* **일상적인 API 사용**은 [기능 제한 사항](https://platform.claude.com/docs/ko/build-with-claude/claude-platform-on-aws#features-not-supported)에 명시된 경우를 제외하고 퍼스트 파티 Claude API와 동일하게 작동합니다. 프로덕션 트래픽을 이동하기 전에 속도 제한을 확인하세요: 새 조직은 Start 티어에 배치되며, 한도 증가는 Anthropic 계정 담당자를 통해 진행됩니다([속도 제한 및 할당량](https://platform.claude.com/docs/ko/build-with-claude/claude-platform-on-aws#rate-limits-and-quotas) 참조).
다르게 동작하는 Claude Enterprise(claude.ai) 조직에 대해서는 [서비스 비교](https://platform.claude.com/docs/ko/build-with-claude/claude-platform-on-aws#claude-platform-on-aws-vs-amazon-bedrock)를 참조하세요.
### 계정 설정 문제 해결
* **"Sign-up failed: Failed to enable OutboundWebIdentityFederation":** 처음 제출할 때 이 배너가 표시되면 **Continue**를 다시 선택하세요. IAM 활성화가 적용되는 데 잠시 시간이 걸릴 수 있습니다.
* **가입 중 진행 표시기가 없음:** 가입에는 몇 분이 걸립니다. AWS가 계정을 프로비저닝하는 동안 페이지에는 진행률 표시줄 없이 정적인 **Sign-up in progress** 배너가 표시됩니다.
* **설정 링크를 따라간 후 "Signed in as a different account" 표시:** **Log out and continue**를 선택하세요. 페이지가 입력한 이메일 주소로 다시 인증합니다.
* **로그인 중 "Not found" 메시지:** 이 메시지는 리디렉션 중에 잠시 나타날 수 있습니다. 무시해도 됩니다.
* **첫 API 호출 후 Usage 페이지에 데이터가 표시되지 않음:** 사용량 데이터가 Claude Console에 표시되기까지 몇 분이 걸릴 수 있습니다.
* **첫 API 호출 시 "Outbound web identity federation is disabled":** 계정당 한 번 페더레이션을 활성화하세요. [아웃바운드 웹 ID 페더레이션 활성화](https://platform.claude.com/docs/ko/build-with-claude/claude-platform-on-aws#enable-outbound-web-identity-federation)를 참조하세요.
## API 호출 전 준비 사항
다음 사항을 확인하세요:
1. Claude Platform on AWS를 구독한 활성 AWS 계정([계정 설정](https://platform.claude.com/docs/ko/build-with-claude/claude-platform-on-aws#set-up-your-account) 참조)
2. 설치 및 구성된 [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-welcome.html)
3. AWS 계정에서 **아웃바운드 웹 ID 페더레이션 활성화**, 일회성 설정 단계([아웃바운드 웹 ID 페더레이션 활성화](https://platform.claude.com/docs/ko/build-with-claude/claude-platform-on-aws#enable-outbound-web-identity-federation) 참조)
4. 워크스페이스 ID([워크스페이스 ID 확인](https://platform.claude.com/docs/ko/build-with-claude/claude-platform-on-aws#obtain-your-workspace-id) 참조)
5. API를 호출할 IAM 권한: 워크스페이스에 대한 `aws-external-anthropic:CreateInference` 작업, 그리고 API 키로 인증하는 경우 `aws-external-anthropic:CallWithBearerToken`([IAM 정책](https://platform.claude.com/docs/ko/build-with-claude/claude-platform-on-aws#iam-policies) 참조)
### 아웃바운드 웹 ID 페더레이션 활성화
Claude Platform on AWS 게이트웨이는 서버 측에서 `sts:GetWebIdentityToken`을 호출하여 Anthropic에 전달할 JWT를 발급합니다. 이 STS 기능은 모든 AWS 계정에서 **기본적으로 비활성화**되어 있습니다. 계정당 한 번 활성화하세요:
```bash CLI
aws iam enable-outbound-web-identity-federation
```
응답이 `[ERROR] (FeatureEnabled) ... already enabled`이면 계정에 이미 설정이 켜져 있으므로 다음 단계로 넘어가면 됩니다. 계정의 발급자 URL을 확인하고 가져오세요:
```bash CLI
aws iam get-outbound-web-identity-federation-info
```
이 단계를 수행하지 않으면 모든 요청이 `"Outbound web identity federation is disabled for your account"`를 반환합니다. 이는 가장 흔한 설정 오류입니다.
### 워크스페이스 ID 확인
계정 설정을 완료한 후 AWS Console에서 워크스페이스를 생성합니다([계정 설정](https://platform.claude.com/docs/ko/build-with-claude/claude-platform-on-aws#set-up-your-account) 참조). 워크스페이스는 단일 AWS 리전에 바인딩됩니다. 워크스페이스 ID는 [Claude Console](https://platform.claude.com/docs/ko/build-with-claude/claude-platform-on-aws#using-the-claude-console)의 **Workspaces** 아래 또는 AWS Console 서비스 페이지의 **Workspaces** 섹션에서 찾을 수 있습니다.
SDK 클라이언트가 자동으로 읽을 수 있도록 `ANTHROPIC_AWS_WORKSPACE_ID` 및 `AWS_REGION` 환경 변수를 설정하세요:
```bash CLI
export ANTHROPIC_AWS_WORKSPACE_ID='wrkspc_01AbCdEf23GhIj'
export AWS_REGION='us-west-2' # Your workspace's AWS region
```
리전은 필수입니다. 리전이 설정되지 않으면 SDK 클라이언트가 오류를 발생시킵니다. 클라이언트를 생성할 때 `aws_region` (typescript, php: `awsRegion`; go: `AWSRegion`; java: `.region()`; csharp: `AwsClientOptions.AwsRegion`)을 전달하거나 `AWS_REGION`(또는 `AWS_DEFAULT_REGION`)을 설정하세요. 모든 AWS 상용 리전이 지원됩니다.
## 인증
Claude Platform on AWS는 두 가지 인증 방법을 지원합니다: Signature Version 4(SigV4) 요청 서명을 사용하는 AWS IAM(기본)과 API 키 인증입니다. 두 방법 모두 동일한 기본 URL과 요청 형식을 사용합니다.
### SigV4 인증
SigV4는 엔터프라이즈 네이티브 경로이며 기존 AWS IAM 정책, 역할, 감사와 통합됩니다. [AWS 기본 자격 증명 공급자 체인](https://docs.aws.amazon.com/sdkref/latest/guide/standardized-credentials.html)에서 지원하는 모든 방법을 사용하여 AWS 자격 증명을 구성하세요:
* 환경 변수(`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_SESSION_TOKEN`)
* 공유 자격 증명 파일(`~/.aws/credentials`)
* SSO 및 `credential_process`를 포함한 공유 구성 파일(`~/.aws/config`)
* IRSA 및 GitHub Actions용 웹 ID(`AWS_WEB_IDENTITY_TOKEN_FILE` 및 `AWS_ROLE_ARN`)
* ECS 컨테이너 자격 증명
* EC2 인스턴스 메타데이터 서비스(IMDS)
자격 증명이 작동하는지 확인하세요:
```bash CLI
aws sts get-caller-identity
```
### API 키 인증
더 간단한 통합 경로(로컬 개발 및 스크립트)의 경우 SigV4 대신 API 키로 인증할 수 있습니다. `ANTHROPIC_AWS_API_KEY` 환경 변수를 설정하거나 클라이언트를 생성할 때 `api_key` (typescript, php: `apiKey`; go: `APIKey`; java: `.apiKey()`; csharp: `AwsClientOptions.ApiKey`)를 전달하세요.
API 키는 **AWS Console**의 **Claude Platform on AWS → API keys**에서 생성합니다. **Generate a key**를 선택한 다음 키 값을 복사하세요. API 키 인증 사용을 허용할 주체에 `aws-external-anthropic:CallWithBearerToken` IAM 작업을 부여하세요.
Claude Platform on AWS용 API 키는 Claude Console이 아닌 AWS Console에서 관리됩니다. 표준 [Claude Console](https://platform.claude.com/)에서 생성한 키(퍼스트 파티 API 액세스용)는 Claude Platform on AWS 엔드포인트에서 작동하지 않습니다.
#### 단기 API 키
별도의 프로세스(예: LLM 게이트웨이, 서버리스 함수, 또는 SigV4는 지원하지 않지만 bearer 토큰 인증은 지원하는 도구)에 자격 증명을 전달해야 하는 워크로드의 경우, AWS Console에서 장기 키를 프로비저닝하는 대신 AWS 자격 증명으로 단기 API 키를 생성하세요.
AWS는 [JavaScript](https://github.com/aws/token-generator-for-aws-external-anthropic-js), [Python](https://github.com/aws/token-generator-for-aws-external-anthropic-python), [Java](https://github.com/aws/token-generator-for-aws-external-anthropic-java)용 토큰 생성기 라이브러리를 게시합니다. 각 라이브러리는 표준 공급자 체인을 통해 AWS 자격 증명을 읽고 `Authorization: Bearer `으로 전송하는 시간 제한 토큰을 반환합니다. 토큰 수명은 기본 12시간이며, 요청한 기간, AWS 자격 증명의 만료 시간, 12시간 중 가장 짧은 값으로 제한됩니다. 설치 및 전체 구성 옵션은 링크된 저장소의 README를 참조하세요.
생성된 토큰은 AWS Console에서 생성한 API 키를 전달하는 것과 같은 방식으로 SDK에 전달하세요:
```python Python
from token_generator_for_aws_external_anthropic import TokenGenerator
from anthropic import AnthropicAWS
token = TokenGenerator(region="us-west-2").get_token()
client = AnthropicAWS(api_key=token, aws_region="us-west-2")
```
```typescript TypeScript
import { getTokenProvider } from "@aws/token-generator-for-aws-external-anthropic";
import AnthropicAws from "@anthropic-ai/aws-sdk";
const tokenProvider = getTokenProvider({ region: "us-west-2" });
const token = await tokenProvider();
const client = new AnthropicAws({ apiKey: token, awsRegion: "us-west-2" });
```
```java Java
import software.amazon.awsexternalanthropic.TokenGenerator;
import software.amazon.awssdk.regions.Region;
import com.anthropic.aws.backends.AwsBackend;
import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
void main() {
String token = TokenGenerator.builder().region(Region.US_WEST_2).build().getToken();
AnthropicClient client = AnthropicOkHttpClient.builder()
.backend(AwsBackend.builder()
.apiKey(token)
.region(Region.US_WEST_2)
.workspaceId(System.getenv("ANTHROPIC_AWS_WORKSPACE_ID"))
.build())
.build();
}
```
토큰을 로컬에서 생성할 수 있다면 프로세스에 이미 SigV4 자격 증명이 있는 것이므로, 일반적으로 SigV4 인증이 더 간단한 선택입니다. API 호출을 수행하는 프로세스가 AWS 자격 증명을 보유한 프로세스와 분리되어 있을 때 단기 키를 사용하세요.
SDK는 단기 키를 자동으로 갱신하지 않습니다. 토큰이 만료되면 새 토큰을 생성하고 새 클라이언트를 구성하세요. 토큰을 사용하는 주체에는 여전히 `aws-external-anthropic:CallWithBearerToken` IAM 작업이 필요합니다.
### 자격 증명 우선순위
플랫폼별 클라이언트는 생성 시 전달한 값부터 시작하여 다음 순서로 인증을 확인합니다:
1. `api_key` (typescript, php: `apiKey`; go: `APIKey`; java: `.apiKey()`; csharp: `AwsClientOptions.ApiKey`) → `Authorization: Bearer` 헤더
2. `aws_access_key` (typescript, php: `awsAccessKey`; go: `AWSAccessKey`; java: `.awsAccessKey()`; csharp: `AwsClientOptions.AwsAccessKey`) + `aws_secret_key` (ruby: `aws_secret_access_key`; typescript, php: `awsSecretAccessKey`; go: `AWSSecretAccessKey`; java: `.awsSecretAccessKey()`; csharp: `AwsClientOptions.AwsSecretAccessKey`) → AWS SigV4
3. `aws_profile` (typescript, php: `awsProfile`; go: `AWSProfile`; java: `.awsProfile()`; csharp: `AwsClientOptions.AwsProfile`) → 명명된 프로필을 사용한 AWS SigV4
4. `ANTHROPIC_AWS_API_KEY` 환경 변수 → `Authorization: Bearer` 헤더
5. 기본 AWS 자격 증명 공급자 체인 → AWS SigV4
### 리전 확인
`aws_region` (typescript, php: `awsRegion`; go: `AWSRegion`; java: `.region()`; csharp: `AwsClientOptions.AwsRegion`)을 설정하지 않으면 클라이언트는 환경에서 `AWS_REGION`을 읽으며, 표준 AWS SDK와의 호환성을 위해 `AWS_DEFAULT_REGION`으로 대체합니다. 리전은 필수이며 기본값이 없습니다: 생성자 인수와 환경 변수가 모두 설정되지 않으면 `AnthropicAWS` (typescript: `AnthropicAws`; csharp: `AnthropicAwsClient`; go: `anthropicaws.NewClient()`; java: `AwsBackend`; php: `Anthropic\Aws\Client`; ruby: `Anthropic::AWSClient`)가 오류를 발생시킵니다.
## SDK 설치
Anthropic의 [클라이언트 SDK](https://platform.claude.com/docs/ko/cli-sdks-libraries/overview)는 Claude Platform on AWS를 지원합니다. SDK는 SigV4 서명, 리전 기반 기본 URL 구성, `anthropic-workspace-id` 헤더를 처리하는 `AnthropicAWS` (typescript: `AnthropicAws`; csharp: `AnthropicAwsClient`; go: `anthropicaws.NewClient()`; java: `AwsBackend`; php: `Anthropic\Aws\Client`; ruby: `Anthropic::AWSClient`)를 제공합니다.
```bash
pip install -U "anthropic[aws]"
```
macOS에서 Homebrew Python 또는 기타 외부 관리 Python 환경을 사용하는 경우, `pip install`이 PEP 668 `externally-managed-environment` 오류로 실패할 수 있습니다. 먼저 가상 환경을 생성하고 활성화하세요: `python3 -m venv .venv && source .venv/bin/activate`.
```bash
npm install @anthropic-ai/aws-sdk
```
```bash
dotnet add package Anthropic.Aws
```
```bash
go get github.com/anthropics/anthropic-sdk-go
```
```kotlin Gradle
implementation("com.anthropic:anthropic-java:3.3.0")
implementation("com.anthropic:anthropic-java-aws:3.3.0")
```
```xml Maven
com.anthropic
anthropic-java
3.3.0
com.anthropic
anthropic-java-aws
3.3.0
```
```bash
composer require anthropic-ai/sdk aws/aws-sdk-php
```
```bash
gem install anthropic aws-sdk-core
```
Claude Platform on AWS용 SDK 클라이언트는 베타 상태입니다.
## 사용 가능한 모델
Claude Platform on AWS에서 사용할 수 있는 모델은 다음과 같습니다:
| Model | Model ID |
| :---------------------------------------------------------------------------------------------------- | :------------------ |
| Claude Fable 5.1 | `claude-fable-5-1` |
| Claude Fable 5 | `claude-fable-5` |
| Claude Opus 5.5 | `claude-opus-5-5` |
| Claude Opus 5 | `claude-opus-5` |
| Claude Opus 4.8 | `claude-opus-4-8` |
| Claude Opus 4.7 | `claude-opus-4-7` |
| Claude Opus 4.6 | `claude-opus-4-6` |
| Claude Opus 4.5 | `claude-opus-4-5` |
| Claude Sonnet 5.5 | `claude-sonnet-5-5` |
| Claude Sonnet 5 | `claude-sonnet-5` |
| Claude Sonnet 4.6 | `claude-sonnet-4-6` |
| Claude Sonnet 4.5 ([deprecated](https://platform.claude.com/docs/ko/about-claude/model-deprecations)) | `claude-sonnet-4-5` |
| Claude Haiku 5.5 | `claude-haiku-5-5` |
| Claude Haiku 4.5 | `claude-haiku-4-5` |
모델 ID는 퍼스트 파티 Claude API와 동일합니다. Bedrock 스타일의 ARN이나 `anthropic.` 접두사는 없습니다.
새 모델은 일반적으로 퍼스트 파티 Claude API와 같은 날 Claude Platform on AWS에 출시됩니다.
최신 Claude 모델로 업그레이드하시나요? Claude Code의 [Claude API 스킬](https://platform.claude.com/docs/ko/agents-and-tools/agent-skills/claude-api-skill#migrating-to-a-newer-claude-model)은 코드베이스 전체에 모델 ID 교체 및 호환성이 깨지는 매개변수 변경 사항을 적용합니다:
Claude Code가 코드를 대신 마이그레이션하도록 하세요
```text
/claude-api migrate 이 프로젝트를 최신 Claude Opus 모델로 마이그레이션해 줘
```
이 스킬은 코드가 대상으로 하는 클라우드 플랫폼을 감지하고 해당 플랫폼에 맞게 모델 ID 형식과 기능 변경 사항을 조정합니다.
## 요청 보내기
Claude Platform on AWS는 퍼스트 파티 Claude API와 동일한 API 엔드포인트를 사용합니다. 차이점은 기본 URL, 인증 방법, 그리고 요청 대상 [워크스페이스](https://platform.claude.com/docs/ko/build-with-claude/claude-platform-on-aws#workspaces)를 식별하는 `anthropic-workspace-id` 헤더입니다. 이 헤더는 Messages API, Models API, Files API, Claude Managed Agents 엔드포인트 호출과 같은 추론 및 리소스 요청에 필수입니다. [Admin API](https://platform.claude.com/docs/ko/manage-claude/admin-api)에 대한 요청에는 필요하지 않습니다.
이 예제를 실행하기 전에 [API 호출 전 준비 사항](https://platform.claude.com/docs/ko/build-with-claude/claude-platform-on-aws#before-making-api-calls)의 단계를 완료하세요.
```bash cURL
# URL과 --aws-sigv4 모두에서 us-west-2를 사용 중인 AWS 리전으로 바꾸세요
# 장기 IAM 사용자 자격 증명을 사용하는 경우 x-amz-security-token 헤더를 생략하세요
curl "https://aws-external-anthropic.us-west-2.api.aws/v1/messages" \
--aws-sigv4 "aws:amz:us-west-2:aws-external-anthropic" \
--user "$AWS_ACCESS_KEY_ID:$AWS_SECRET_ACCESS_KEY" \
-H "x-amz-security-token: $AWS_SESSION_TOKEN" \
-H "content-type: application/json" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-workspace-id: $ANTHROPIC_AWS_WORKSPACE_ID" \
-d '{
"model": "claude-sonnet-5-5",
"max_tokens": 1024,
"messages": [
{"role": "user", "content": "Hello!"}
]
}'
```
```bash CLI
# us-west-2를 사용 중인 AWS 리전으로 바꾸세요
# ant는 ANTHROPIC_API_KEY를 읽습니다. AWS Console에서 키를 생성하세요
# (API 키 인증을 참조하세요).
export ANTHROPIC_API_KEY="YOUR_AWS_API_KEY"
ant messages create \
--base-url https://aws-external-anthropic.us-west-2.api.aws \
--workspace-id "$ANTHROPIC_AWS_WORKSPACE_ID" \
--model claude-sonnet-5-5 \
--max-tokens 1024 \
--message '{role: user, content: "Hello!"}'
```
```python Python
from anthropic import AnthropicAWS
client = AnthropicAWS()
message = client.messages.create(
model="claude-sonnet-5-5",
max_tokens=1024,
messages=[{"role": "user", "content": "Hello!"}],
)
print(message)
```
```typescript TypeScript
import AnthropicAws from "@anthropic-ai/aws-sdk";
const client = new AnthropicAws();
const message = await client.messages.create({
model: "claude-sonnet-5-5",
max_tokens: 1024,
messages: [{ role: "user", content: "Hello!" }]
});
console.log(message);
```
```csharp C#
using Anthropic;
using Anthropic.Aws;
var client = new AnthropicAwsClient();
var message = await client.Messages.Create(new()
{
Model = Model.ClaudeSonnet5_5,
MaxTokens = 1024,
Messages = [new UserMessageParam { Content = "Hello!" }]
});
Console.WriteLine(message);
```
```go Go
client, err := anthropicaws.NewClient(context.Background(), anthropicaws.ClientConfig{})
if err != nil {
panic(err)
}
message, err := client.Messages.New(context.Background(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeSonnet5_5,
MaxTokens: 1024,
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("Hello!")),
},
})
if err != nil {
panic(err)
}
fmt.Println(message)
```
```java Java
import com.anthropic.aws.backends.AwsBackend;
import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.messages.Message;
import com.anthropic.models.messages.MessageCreateParams;
import com.anthropic.models.messages.Model;
void main() {
AnthropicClient client = AnthropicOkHttpClient.builder()
.backend(AwsBackend.fromEnv())
.build();
Message message = client.messages().create(
MessageCreateParams.builder()
.model(Model.CLAUDE_SONNET_5_5)
.maxTokens(1024)
.addUserMessage("Hello!")
.build()
);
IO.println(message);
}
```
```php PHP
use Anthropic\Aws\Client;
$client = new Client();
$message = $client->messages->create(
model: 'claude-sonnet-5-5',
maxTokens: 1024,
messages: [['role' => 'user', 'content' => 'Hello!']],
);
echo $message;
```
```ruby Ruby
require "anthropic"
client = Anthropic::AWSClient.new
message = client.messages.create(
model: "claude-sonnet-5-5",
max_tokens: 1024,
messages: [{ role: "user", content: "Hello!" }]
)
puts message
```
클라이언트는 환경에서 `AWS_REGION`(또는 `AWS_DEFAULT_REGION`)과 `ANTHROPIC_AWS_WORKSPACE_ID`를 읽습니다. 클라이언트를 생성할 때 `aws_region` (typescript, php: `awsRegion`; go: `AWSRegion`; java: `.region()`; csharp: `AwsClientOptions.AwsRegion`) 또는 `workspace_id` (typescript, php: `workspaceId`; go: `WorkspaceID`; java: `.workspaceId()`; csharp: `AwsClientOptions.WorkspaceId`)를 전달하여 둘 중 하나를 재정의할 수 있습니다. 리전과 워크스페이스 ID는 모두 필수입니다. 둘 중 하나라도 확인할 수 없으면 생성자가 오류를 발생시킵니다.
`x-amz-security-token` 헤더(cURL)는 IAM 역할, SSO 또는 STS와 같은 임시 자격 증명에만 필요합니다. 장기 IAM 사용자 자격 증명을 사용할 때는 생략하세요. SDK 클라이언트는 자격 증명 소스에 따라 이를 자동으로 처리합니다.
`--aws-sigv4` 값은 `aws:amz::` 형식을 따릅니다. SigV4 서비스 이름은 `aws-external-anthropic`이며, 리전은 엔드포인트 URL의 리전과 일치해야 합니다. 둘 중 하나라도 일치하지 않으면 구체적인 진단 대신 일반적인 서명 거부 오류가 발생합니다.
### 컨텍스트 윈도우
Claude Platform on AWS의 "context window"(컨텍스트 윈도우) 크기는 퍼스트 파티 Claude API와 동일합니다. 모델별 한도는 [컨텍스트 윈도우](https://platform.claude.com/docs/ko/build-with-claude/context-windows)를 참조하세요.
## 기능 지원
Claude Platform on AWS는 Claude API 엔드포인트를 직접 사용하므로, 퍼스트 파티 Claude API와 완전한 기능 동등성을 제공합니다([기능 제한 사항](https://platform.claude.com/docs/ko/build-with-claude/claude-platform-on-aws#features-not-supported)에 명시된 경우 제외):
* **기능 액세스:** Anthropic이 두 플랫폼을 모두 운영하므로, 대부분의 새 기능과 베타 헤더는 별도의 통합 단계 없이 Claude Platform on AWS에서 사용할 수 있게 됩니다. 예외 사항은 [기능 제한 사항](https://platform.claude.com/docs/ko/build-with-claude/claude-platform-on-aws#features-not-supported)을 참조하세요.
* **베타 기능:** Claude API에서와 마찬가지로 표준 `anthropic-beta` 헤더를 전달하여 베타 기능에 액세스하세요.
* **Agent Skills:** Claude API와 동일한 `container.skills` 매개변수로 사전 구축 및 사용자 정의 [Agent Skills](https://platform.claude.com/docs/ko/agents-and-tools/agent-skills/overview)를 사용하세요. 모든 사전 구축 Skills(PowerPoint, Excel, Word, PDF)는 별도 설정 없이 바로 작동합니다.
* **코드 실행:** [코드 실행 도구](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/code-execution-tool)를 사용하여 Anthropic의 관리형 샌드박스에서 코드를 실행하세요.
* **도구 사용:** 컴퓨터 사용 및 브라우저 사용 도구 세트를 제외한 모든 ["tool use"(도구 사용) 기능](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/overview)을 사용할 수 있습니다. [지원되지 않는 기능](https://platform.claude.com/docs/ko/build-with-claude/claude-platform-on-aws#features-not-supported)을 참조하세요.
* **사고:** [적응형 사고](https://platform.claude.com/docs/ko/build-with-claude/thinking), [effort 매개변수](https://platform.claude.com/docs/ko/build-with-claude/effort), 그리고 이를 지원하는 모델에서는 ["extended thinking"(확장 사고)](https://platform.claude.com/docs/ko/build-with-claude/extended-thinking)이 Claude API와 동일한 매개변수로 작동합니다.
* **스트리밍:** 실시간 응답을 위한 완전한 SSE "streaming"(스트리밍) 지원.
* **배치 처리:** 높은 처리량의 워크로드를 위해 배치 요청을 제출하세요.
* **프롬프트 캐싱:** 도구, 시스템 프롬프트, 메시지 기록을 캐싱하여 지연 시간과 비용을 줄이세요. 모든 "prompt caching"(프롬프트 캐싱) 기능(5분 TTL, 1시간 TTL, 자동 캐싱)을 사용할 수 있습니다.
* **Files API:** 파일을 업로드하고 여러 요청에서 참조하세요.
* **고객 관리형 암호화 키(CMEK):** [CMEK](https://platform.claude.com/docs/ko/manage-claude/cmek)는 [AWS KMS](https://platform.claude.com/docs/ko/manage-claude/cmek-aws-kms) 키로만 사용할 수 있습니다. Google Cloud KMS 및 Azure Key Vault 키는 등록할 수 없습니다. 키는 연결되는 워크스페이스와 동일한 AWS 계정 및 리전에 있는 단일 리전 KMS 키여야 하며, 키 정책은 `aws-external-anthropic.amazonaws.com` 서비스 주체에 액세스 권한을 부여해야 합니다. [Claude Platform on AWS에서 CMEK 설정](https://platform.claude.com/docs/ko/manage-claude/cmek-claude-platform-on-aws)을 참조하세요. 키는 [Claude Console](https://platform.claude.com/docs/ko/build-with-claude/claude-platform-on-aws#using-the-claude-console)에서 등록하고 연결하세요. 외부 키 엔드포인트도 사용할 수 있으며, [IAM 작업](https://platform.claude.com/docs/ko/api/claude-platform-on-aws-iam-actions#encryption-keys)을 통해 권한이 부여됩니다. 별도의 검증 단계는 없습니다: 키를 워크스페이스에 연결할 때 암묵적으로 검증되므로(연결 호출이 암호화/복호화 왕복을 수행함), 키 정책 문제는 등록 시점이 아닌 연결 시점에 드러납니다.
* **Compliance API:** [Compliance API](https://platform.claude.com/docs/ko/manage-claude/compliance-api)를 사용할 수 있습니다. 액세스는 AWS IAM [`ListComplianceActivities` 작업](https://platform.claude.com/docs/ko/api/claude-platform-on-aws-iam-actions#compliance)을 통해 권한이 부여됩니다.
Amazon Bedrock과의 기능 가용성 차이는 [비교 표](https://platform.claude.com/docs/ko/build-with-claude/claude-platform-on-aws#claude-platform-on-aws-vs-amazon-bedrock)를 참조하세요.
### Claude Managed Agents
[Claude Managed Agents](https://platform.claude.com/docs/ko/managed-agents/overview)는 Claude Platform on AWS에서 사용할 수 있으며, 여기에는 [에이전트](https://platform.claude.com/docs/ko/managed-agents/agent-setup), [환경](https://platform.claude.com/docs/ko/managed-agents/environments), [세션](https://platform.claude.com/docs/ko/managed-agents/sessions), [예약 배포](https://platform.claude.com/docs/ko/managed-agents/scheduled-deployments), [자격 증명 볼트](https://platform.claude.com/docs/ko/managed-agents/vaults), [메모리 저장소](https://platform.claude.com/docs/ko/managed-agents/memory), [웹훅](https://platform.claude.com/docs/ko/managed-agents/webhooks), [멀티에이전트 오케스트레이션](https://platform.claude.com/docs/ko/managed-agents/multiagent-orchestration), [자체 호스팅 샌드박스](https://platform.claude.com/docs/ko/managed-agents/self-hosted-sandboxes)가 포함됩니다.
Claude Platform on AWS의 세션과 자체 호스팅 워커는 퍼스트 파티 Claude Managed Agents와 다음 세 가지 점에서 다릅니다:
* **자율 세션 재인증:** 세션은 [사용자 이벤트](https://platform.claude.com/docs/ko/managed-agents/reference#event-types) 없이 최대 6시간 동안 자율적으로 실행될 수 있습니다. 6시간이 지나면 세션을 계속하기 전에 재인증이 필요합니다. 재인증하려면 세션에 사용자 역할 이벤트를 아무것이나 전송하세요([이벤트 및 스트리밍](https://platform.claude.com/docs/ko/managed-agents/events-and-streaming) 참조). 퍼스트 파티 Claude Managed Agents에는 자율 세션 실행 시간 제한이 없습니다.
* **[자체 호스팅 환경의 메모리 저장소](https://platform.claude.com/docs/ko/managed-agents/self-hosted-sandboxes-memory):** 자체 호스팅 환경에서 실행되는 세션은 메모리 저장소를 연결할 수 없으며, 메모리 저장소를 포함한 세션은 생성 시 거부됩니다. 클라우드 환경의 세션은 평소와 같이 메모리 저장소를 연결합니다. 퍼스트 파티 Claude Managed Agents에서는 클라우드 환경과 자체 호스팅 환경의 세션 모두 메모리 저장소를 연결할 수 있습니다.
* **[자체 호스팅 환경의 워커 인증](https://platform.claude.com/docs/ko/managed-agents/self-hosted-sandboxes#prerequisites):** 워커는 환경 키가 아닌 AWS IAM(SigV4) 또는 [AWS Console에서 생성한 API 키](https://platform.claude.com/docs/ko/build-with-claude/claude-platform-on-aws#api-key-authentication)로 인증합니다. Claude Console에서 생성한 환경 키는 Claude Platform on AWS 엔드포인트에서 작동하지 않습니다.
### 지원되지 않는 기능
다음 기능은 현재 Claude Platform on AWS에서 사용할 수 없습니다:
* **HIPAA 대응:** Anthropic의 HIPAA 대응 프로그램은 사용할 수 없습니다. [API 및 데이터 보존](https://platform.claude.com/docs/ko/manage-claude/api-and-data-retention)을 참조하세요.
* **Computer use 및 browser use 도구 세트:** `computer_toolset_20260801` 및 `browser_toolset_20260801`은 현재 Claude Platform on AWS에서 사용할 수 없습니다. 베타 computer use 도구 버전은 [이전 도구 버전](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/computer-use-tool#earlier-tool-versions)에 나열된 모델에서 계속 사용할 수 있습니다.
- **Admin API:** 워크스페이스 엔드포인트(`/v1/organizations/workspaces`에 대한 생성, 조회, 목록, 업데이트, 보관), 외부 키 엔드포인트([CMEK](https://platform.claude.com/docs/ko/manage-claude/cmek)용 `/v1/organizations/external_keys`에 대한 등록, 조회, 목록, 업데이트, 삭제. 키는 검증 엔드포인트가 아니라 워크스페이스에 연결될 때 검증됩니다), 그리고 [텔레메트리 대상 엔드포인트](https://platform.claude.com/docs/ko/api/claude-platform-on-aws-iam-actions#telemetry-destinations)를 사용할 수 있습니다. 기타 Admin API 엔드포인트(조직 구성원, 워크스페이스 구성원, 초대, API 키, 사용량 보고서, 비용 보고서, 속도 제한 보고서)는 현재 사용할 수 없습니다. 대신 [Claude Console](https://platform.claude.com/docs/ko/build-with-claude/claude-platform-on-aws#using-the-claude-console)에서 사용량 및 비용 데이터를 확인하세요. 조직 구성원 관리는 AWS IAM이 담당합니다.
- **워크스페이스 구성원 관리:** 개별 워크스페이스에 사용자를 추가하거나 제거하는 기능은 사용할 수 없습니다. 워크스페이스 ARN에 대한 AWS IAM 정책이 액세스를 제어합니다.
- **Claude Code 워크스페이스 및 Analytics API:** 자동 속도 제한이 적용되는 Claude Code 워크스페이스는 사용할 수 없습니다. Claude Code 사용량은 전용 화면이 아닌 일반 사용량 보기에 표시됩니다.
- **OAuth 인증:** 지원되지 않습니다. SigV4 또는 API 키 인증을 사용하세요.
- **Fast mode:** Claude Platform on AWS에서 사용할 수 없습니다.
- **OpenAI 호환 API 엔드포인트:** Claude Platform on AWS에서 사용할 수 없습니다.
- **MCP 터널:** 공용 인터넷을 통해 노출된 MCP 서버만 지원됩니다.
## 데이터 레지던시
Claude Platform on AWS는 다음 추론 지역을 지원합니다:
* **US:** 추론이 미국 데이터 센터 내에서 이루어집니다. 1.1배의 가격 배수가 적용됩니다.
* **Global:** 추론이 전 세계 Anthropic 운영 데이터 센터 어디로든 라우팅될 수 있습니다. 표준 가격이 적용됩니다.
워크스페이스가 바인딩된 AWS 리전은 호출하는 게이트웨이 엔드포인트와 AWS 측 리소스(IAM, CloudTrail, 청구)의 범위를 결정합니다. 모델 추론이 실행되는 위치를 고정하지는 않습니다. 추론을 특정 지역으로 고정하려면 각 요청에 `inference_geo`를 설정하거나 워크스페이스 기본값을 구성하세요.
`inference_geo` 매개변수로 요청별 추론 지역을 설정하세요:
`inference_geo` 매개변수는 Claude 4.6 이상 모델에서 지원됩니다. Claude Opus 4.5, Claude Sonnet 4.5(지원 중단) 또는 Claude Haiku 4.5에서 `inference_geo`를 포함한 요청은 400 오류를 반환합니다. 모델 가용성에 대한 자세한 내용은 [데이터 레지던시](https://platform.claude.com/docs/ko/manage-claude/data-residency)를 참조하세요.
```bash cURL
# URL과 --aws-sigv4 모두에서 us-west-2를 사용 중인 AWS 리전으로 바꾸세요
# 장기 IAM 사용자 자격 증명을 사용하는 경우 x-amz-security-token 헤더를 생략하세요
curl "https://aws-external-anthropic.us-west-2.api.aws/v1/messages" \
--aws-sigv4 "aws:amz:us-west-2:aws-external-anthropic" \
--user "$AWS_ACCESS_KEY_ID:$AWS_SECRET_ACCESS_KEY" \
-H "x-amz-security-token: $AWS_SESSION_TOKEN" \
-H "content-type: application/json" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-workspace-id: $ANTHROPIC_AWS_WORKSPACE_ID" \
-d '{
"model": "claude-sonnet-5-5",
"max_tokens": 1024,
"inference_geo": "us",
"messages": [
{"role": "user", "content": "Hello!"}
]
}'
```
```bash CLI
# us-west-2를 사용 중인 AWS 리전으로 바꾸세요
# ant는 ANTHROPIC_API_KEY를 읽습니다. AWS Console에서 키를 생성하세요
# (API 키 인증을 참조하세요).
export ANTHROPIC_API_KEY="YOUR_AWS_API_KEY"
ant messages create \
--base-url https://aws-external-anthropic.us-west-2.api.aws \
--workspace-id "$ANTHROPIC_AWS_WORKSPACE_ID" \
--model claude-sonnet-5-5 \
--max-tokens 1024 \
--inference-geo us \
--message '{role: user, content: "Hello!"}'
```
```python Python
from anthropic import AnthropicAWS
client = AnthropicAWS()
message = client.messages.create(
model="claude-sonnet-5-5",
max_tokens=1024,
inference_geo="us",
messages=[{"role": "user", "content": "Hello!"}],
)
print(message)
```
```typescript TypeScript
import AnthropicAws from "@anthropic-ai/aws-sdk";
const client = new AnthropicAws();
const message = await client.messages.create({
model: "claude-sonnet-5-5",
max_tokens: 1024,
inference_geo: "us",
messages: [{ role: "user", content: "Hello!" }]
});
console.log(message);
```
```csharp C#
using Anthropic;
using Anthropic.Aws;
var client = new AnthropicAwsClient();
var message = await client.Messages.Create(new()
{
Model = Model.ClaudeSonnet5_5,
MaxTokens = 1024,
InferenceGeo = "us",
Messages = [new UserMessageParam { Content = "Hello!" }]
});
Console.WriteLine(message);
```
```go Go
client, err := anthropicaws.NewClient(context.Background(), anthropicaws.ClientConfig{})
if err != nil {
panic(err)
}
message, err := client.Messages.New(context.Background(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeSonnet5_5,
MaxTokens: 1024,
InferenceGeo: anthropic.String("us"),
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("Hello!")),
},
})
if err != nil {
panic(err)
}
fmt.Println(message)
```
```java Java
import com.anthropic.aws.backends.AwsBackend;
import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.messages.Message;
import com.anthropic.models.messages.MessageCreateParams;
import com.anthropic.models.messages.Model;
void main() {
AnthropicClient client = AnthropicOkHttpClient.builder()
.backend(AwsBackend.fromEnv())
.build();
Message message = client.messages().create(
MessageCreateParams.builder()
.model(Model.CLAUDE_SONNET_5_5)
.maxTokens(1024)
.inferenceGeo("us")
.addUserMessage("Hello!")
.build()
);
IO.println(message);
}
```
```php PHP
use Anthropic\Aws\Client;
$client = new Client();
$message = $client->messages->create(
model: 'claude-sonnet-5-5',
maxTokens: 1024,
inferenceGeo: 'us',
messages: [['role' => 'user', 'content' => 'Hello!']],
);
echo $message;
```
```ruby Ruby
require "anthropic"
client = Anthropic::AWSClient.new
message = client.messages.create(
model: "claude-sonnet-5-5",
max_tokens: 1024,
inference_geo: "us",
messages: [{ role: "user", content: "Hello!" }]
)
puts message
```
`inference_geo`를 생략하면 요청은 워크스페이스의 `default_inference_geo`가 구성되어 있는 경우 이를 사용하고, 그렇지 않으면 `global`을 사용합니다.
워크스페이스 수준의 추론 지역 제어(`allowed_inference_geos` 및 `default_inference_geo`)도 Claude Platform on AWS에서 사용할 수 있습니다. [워크스페이스 수준 제한](https://platform.claude.com/docs/ko/manage-claude/data-residency#workspace-level-restrictions)을 참조하세요.
## 워크스페이스
Claude Platform on AWS의 추론 및 리소스 요청은 워크스페이스를 대상으로 합니다. 이러한 API 호출에서 `anthropic-workspace-id` 헤더에 워크스페이스 ID를 전달합니다. 워크스페이스 ID는 `wrkspc_` 뒤에 영숫자 식별자가 오는 태그 형식을 사용합니다(예: `wrkspc_01AbCdEf23GhIj`). 아직 워크스페이스 ID가 없다면 [워크스페이스 ID 확인하기](https://platform.claude.com/docs/ko/build-with-claude/claude-platform-on-aws#obtain-your-workspace-id)를 참조하세요.
### 워크스페이스 범위
워크스페이스는 단일 AWS 리전에 바인딩됩니다. `us-west-2`에서 생성된 워크스페이스는 `us-west-2` 엔드포인트를 통해서만 액세스할 수 있습니다. 사용량, 할당량, 비용, 파일, 배치, Skills는 모두 워크스페이스별로 집계되므로 Claude Console에서 리전별 세부 내역을 확인할 수 있습니다.
워크스페이스는 Claude Platform on AWS의 기본 IAM 리소스 역할도 합니다. 워크스페이스 ARN을 사용하는 AWS IAM 정책을 통해 특정 워크스페이스에 대한 액세스를 허용하거나 거부합니다. ARN의 리소스 세그먼트는 `anthropic-workspace-id` 헤더에 전달하는 것과 동일한 `wrkspc_` 접두사 ID입니다:
```text wrap
arn:aws:aws-external-anthropic:{region}:{account-id}:workspace/{workspace-id}
```
예를 들면 다음과 같습니다:
```text wrap
arn:aws:aws-external-anthropic:us-west-2:123456789012:workspace/wrkspc_01AbCdEf23GhIj
```
정책 예시는 [IAM 정책](https://platform.claude.com/docs/ko/build-with-claude/claude-platform-on-aws#iam-policies)을 참조하세요.
### 워크스페이스 관리
AWS Console의 **Workspaces** 페이지 또는 [Admin API](https://platform.claude.com/docs/ko/manage-claude/admin-api) 워크스페이스 엔드포인트를 사용하여 추가 워크스페이스를 생성하거나, 워크스페이스 이름을 변경하거나, 워크스페이스를 보관할 수 있습니다. 이러한 엔드포인트에는 `anthropic-workspace-id` 헤더가 필요하지 않습니다. 생성 및 목록은 조직을 대상으로 작동하며, 조회, 업데이트, 보관은 URL 경로에서 워크스페이스 ID를 받습니다. 새 워크스페이스는 생성 시 호출한 엔드포인트의 AWS 리전에 바인딩됩니다([워크스페이스 범위](https://platform.claude.com/docs/ko/build-with-claude/claude-platform-on-aws#workspace-scoping) 참조). Admin 역할이 있으면 Claude Console의 **Workspaces** 페이지에서도 워크스페이스를 생성, 이름 변경, 보관할 수 있습니다.
## Claude Console 사용하기
Claude Platform on AWS는 [platform.claude.com](https://platform.claude.com)의 표준 Claude Console을 사용합니다. AWS Console에서 로그인하면 Claude Console 사이드바 왼쪽 하단에 **Account managed by AWS** 표시가 나타나고, Console의 범위가 Claude Platform on AWS 조직으로 지정됩니다. 사용량 분석, 비용 세부 내역, 속도 제한 확인, 워크스페이스 관리 기능과 함께 파일, Agent Skills, 배치 작업, Claude Managed Agents 리소스(에이전트, 세션, 환경, 자격 증명 볼트, 메모리 저장소, 웹훅)를 관리하는 페이지를 제공합니다.
### 로그인
Claude Console에 대한 액세스는 AWS IAM을 통해 페더레이션됩니다. 최초 로그인 전체 흐름은 [계정 설정하기](https://platform.claude.com/docs/ko/build-with-claude/claude-platform-on-aws#set-up-your-account)를 참조하세요. 요약하면 다음과 같습니다:
1. `aws-external-anthropic:AssumeConsole` 권한이 있는 IAM 역할을 수임합니다. [Claude Platform on AWS용 IAM 작업](https://platform.claude.com/docs/ko/api/claude-platform-on-aws-iam-actions#console-access)을 참조하세요.
2. [AWS Console](https://console.aws.amazon.com/)에서 Claude Platform on AWS 페이지로 이동합니다.
3. **Open Claude Console**을 선택합니다. AWS Console이 JWT를 발급하고 `platform.claude.com`으로 리디렉션합니다.
4. 최초 로그인 시 이메일 주소를 입력하라는 메시지가 표시됩니다. 업무용 이메일을 입력하세요. 플랫폼이 Claude Console 사용자를 즉시(just-in-time) 프로비저닝합니다.
두 가지 Claude Console 역할인 **Admin**과 **Developer**를 사용할 수 있습니다. Admin 역할은 Claude Platform on AWS에서 사용 가능한 모든 Claude Console 페이지와 설정에 대한 액세스 권한을 부여합니다. Developer 역할은 사용량, 비용, 속도 제한, 워크스페이스 정보에 대한 읽기 권한을 부여합니다. 주체에 Admin 또는 Developer 역할을 할당하려면 Anthropic 계정 담당자에게 문의하세요.
### 사용 가능한 페이지
**AWS 게이트웨이 경유** 열은 해당 페이지가 AWS 게이트웨이를 통해 데이터를 읽고 쓰는지(따라서 [IAM 작업](https://platform.claude.com/docs/ko/api/claude-platform-on-aws-iam-actions)의 적용을 받는지)를 나타냅니다. **아니요**로 표시된 페이지는 Anthropic에서 조직 수준 메타데이터를 직접 읽으며 IAM 작업 검사를 거치지 않습니다.
| 페이지 | 사용 가능 | AWS 게이트웨이 경유 | 참고 |
| --------------------- | ------ | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Usage** | 예 | 아니요 | 모델, 워크스페이스, 차원별 토큰 사용량을 확인합니다. 요청 후 데이터가 표시되기까지 몇 분이 걸릴 수 있습니다. |
| **Cost** | 예 | 아니요 | 모델 및 워크스페이스별 비용 세부 내역을 확인합니다. AWS Cost Explorer에는 집계된 [Claude Consumption Unit(CCU)](https://platform.claude.com/docs/ko/build-with-claude/claude-platform-on-aws#billing) 항목이 표시됩니다. |
| **Rate limits** | 예 | 아니요 | 속도 제한을 확인합니다(읽기 전용). 티어 상향은 Anthropic 계정 담당자를 통해 진행됩니다. [속도 제한 및 할당량](https://platform.claude.com/docs/ko/build-with-claude/claude-platform-on-aws#rate-limits-and-quotas)을 참조하세요. |
| **Workspaces** | 예 | 예(지출 한도 제외) | 리전별 워크스페이스를 확인합니다. Admin 역할이 있으면 워크스페이스를 생성, 이름 변경, 보관하고 워크스페이스별 [지출 한도](https://platform.claude.com/docs/ko/build-with-claude/claude-platform-on-aws#spend-limits)를 설정할 수도 있습니다. |
| **Encryption keys** | 예 | 예 | Claude Console의 [Data retention](https://platform.claude.com/settings/privacy#encryption-keys) 페이지(`platform.claude.com/settings/privacy`)의 한 섹션으로, 페이지 상단 드롭다운 메뉴에서 **Organization**이 선택된 경우에 표시됩니다. 여기에서 [CMEK](https://platform.claude.com/docs/ko/manage-claude/cmek-claude-platform-on-aws)용 AWS KMS 키를 등록합니다(Admin 역할). 등록된 키를 워크스페이스에 연결하려면 해당 드롭다운 메뉴에서 워크스페이스를 선택한 다음 **Encryption key** 아래에서 키를 선택하세요. |
| **Files** | 예 | 예 | 업로드된 파일을 확인하고 관리합니다. |
| **Skills** | 예 | 예 | Agent Skills를 확인하고 관리합니다. |
| **Batches** | 예 | 예 | 배치 처리 작업을 확인하고 관리합니다. |
| **Agents** | 예 | 예 | 에이전트 정의를 확인하고 관리합니다. |
| **Sessions** | 예 | 예 | 에이전트 세션과 이벤트 기록을 확인합니다. |
| **Environments** | 예 | 예 | 세션용 클라우드 샌드박스 구성을 확인하고 관리합니다. |
| **Credential vaults** | 예 | 예 | 세션 인증용 자격 증명 볼트를 확인하고 관리합니다. |
| **Memory stores** | 예 | 예 | 영구 에이전트 메모리를 확인하고 관리합니다. |
| **Webhooks** | 예 | 예 | 웹훅 엔드포인트를 확인하고 관리합니다. |
| **API keys** | 아니요 | 해당 없음 | AWS Console(**Claude Platform on AWS → API keys**)에서 API 키를 관리합니다. [API 키 인증](https://platform.claude.com/docs/ko/build-with-claude/claude-platform-on-aws#api-key-authentication)을 참조하세요. |
| **Members** | 아니요 | 해당 없음 | 해당되지 않습니다. AWS IAM이 액세스를 관리합니다. |
| **Billing** | 예(제한적) | 아니요 | 조직 월간 지출 한도를 설정합니다. [지출 한도](https://platform.claude.com/docs/ko/build-with-claude/claude-platform-on-aws#spend-limits)를 참조하세요. 청구서 발행은 AWS Marketplace가 관리합니다. 비용 세부 내역은 Cost 페이지에서 확인하세요. |
| **Claude Code** | 아니요 | 해당 없음 | Claude Code 사용량은 Usage 페이지에서 확인하세요. |
### 조직 전환
Claude Console은 Claude Platform on AWS에 대한 조직 전환을 지원하지 않습니다. 다른 조직에 액세스하려면 로그아웃한 후 해당 조직의 AWS 계정에 대한 IAM 역할을 사용하여 AWS Console을 통해 다시 인증하세요.
## 속도 제한 및 할당량
Claude Platform on AWS의 조직은 Start 티어에 배치됩니다. 속도 제한은 AWS 할당량 시스템이 아닌 Anthropic이 직접 관리합니다.
Claude Platform on AWS의 조직은 유료 AWS Marketplace 청구서 이력이 쌓이면 자동으로 더 높은 사용량 티어로 이동할 수 있습니다. Claude Console의 셀프 서비스 **Request tier increase** 흐름은 사용할 수 없으며, 대신 Rate limits 페이지에서 Anthropic 계정 담당자에게 문의하도록 안내합니다.
더 높은 한도를 요청하려면 Anthropic 계정 담당자 또는 [Anthropic 지원팀](https://support.claude.com)에 문의하세요. 요청 시 다음 내용을 포함하세요:
* 한도 상향이 필요한 모델
* 각 모델의 분당 최대 입력 토큰 수 및 분당 출력 토큰 수(일일 합계 아님)
* 입력 중 캐시되거나 반복되는 컨텍스트의 대략적인 비율(대부분의 모델에서 캐시 읽기는 입력 토큰 한도에 포함되지 않습니다. [캐시 인식 ITPM](https://platform.claude.com/docs/ko/api/rate-limits#cache-aware-itpm) 참조)
사용량 티어는 고정된 단계입니다. 각 티어는 속도 제한과 [월간 지출 상한](https://platform.claude.com/docs/ko/build-with-claude/claude-platform-on-aws#spend-limits)을 함께 묶으며, 더 높은 티어로 이동하면 둘 다 상향됩니다. 티어 세부 정보와 모델별 한도는 [속도 제한](https://platform.claude.com/docs/ko/api/rate-limits)을 참조하세요.
## 청구
Claude Platform on AWS는 [AWS Marketplace](https://aws.amazon.com/marketplace)를 통해 청구됩니다. 사용량은 Claude Consumption Unit(CCU) 단위로 표시되며, 시간 단위로 측정되고 AWS 청구서에 월 단위로 후불 청구됩니다. CCU는 선불 크레딧이 아닙니다. CCU 잔액이나 약정은 없습니다.
CCU 가격, 환산 방식, 할인 적용, 모델별 토큰 요금은 [Claude Platform on AWS 가격](https://platform.claude.com/docs/ko/about-claude/pricing#claude-platform-on-aws-pricing)을 참조하세요.
### 지출 한도
Start, Build, Scale 사용량 티어에는 각각 월간 지출 상한이 있습니다. 현재 값은 [티어별 지출 상한](https://platform.claude.com/docs/ko/api/rate-limits#spend-limits)을 참조하세요. 조직의 해당 월 사용량이 티어 상한에 도달하면 다음 달 1일 00:00 UTC까지 API 요청이 [지출 상한 오류](https://platform.claude.com/docs/ko/api/rate-limits#reaching-your-spend-cap)와 함께 실패하며, 그 전에 재시도해도 성공하지 않습니다. 지출 상한과 속도 제한은 같은 티어에 속합니다. 상한을 높이거나 상한 도달 후 액세스를 복원하려면 Anthropic 계정 담당자 또는 [Anthropic 지원팀](https://support.claude.com)을 통해 티어 상향을 요청하세요([속도 제한 및 할당량](https://platform.claude.com/docs/ko/build-with-claude/claude-platform-on-aws#rate-limits-and-quotas) 참조).
Billing 페이지의 **Email recipients** 아래에 수신자를 한 명 이상 추가한 후에는 상한보다 낮은 자체 월간 지출 한도를 설정할 수도 있습니다:
* **조직 지출 한도:** [Claude Console](https://platform.claude.com/docs/ko/build-with-claude/claude-platform-on-aws#using-the-claude-console)의 [Settings > Billing](https://platform.claude.com/settings/billing)으로 이동하여 월간 지출 한도를 설정하세요.
* **워크스페이스 지출 한도:** Claude Console의 [Workspaces](https://platform.claude.com/settings/workspaces) 페이지(`platform.claude.com/settings/workspaces`)에서 워크스페이스를 선택하세요. 열리는 패널에서 **Spend limits**를 클릭하세요.
사용량이 설정한 한도에 도달하면 다음 달 1일 00:00 UTC까지 또는 한도를 높이거나 제거할 때까지 요청이 HTTP 400과 함께 실패합니다([지출 한도 오류](https://platform.claude.com/docs/ko/api/rate-limits#setting-your-own-spend-limit) 참조).
지출은 정가 기준으로 계산되며 최근 사용량이 반영되기까지 약 2시간이 걸릴 수 있으므로, 요청이 실패하기 시작하기 전에 사용량이 상한이나 한도를 초과할 수 있습니다. 초과분은 청구됩니다. 티어 상한 또는 조직 지출 한도로 인해 요청이 중단되면 Billing 페이지의 **Email recipients** 아래에 나열된 수신자에게 이메일 알림이 전송됩니다. 모든 관리자와 같은 역할 기반 수신자는 Claude Platform on AWS에서 사용할 수 없습니다. 티어 상한 알림은 AWS Marketplace 가입 시 사용한 이메일 주소로도 전송됩니다.
## 모니터링 및 로깅
AWS CloudTrail은 Claude Platform on AWS에 대한 모든 요청을 캡처할 수 있습니다. 워크스페이스, 외부 키, 텔레메트리 대상, 규정 준수, 볼트, 웹훅 작업은 기본적으로 관리 이벤트(Management events)로 기록됩니다. 추론, 배치, 파일, 스킬, 모델, 사용자 프로필, Claude Managed Agents 작업(볼트 및 웹훅 제외)은 데이터 이벤트(Data events)로 분류되며 명시적인 데이터 이벤트 로깅 구성이 필요하고, 이에 따라 추가 CloudTrail 요금이 발생합니다. 전체 이벤트 유형 분류는 [IAM 작업 참조](https://platform.claude.com/docs/ko/api/claude-platform-on-aws-iam-actions#route-to-action-mapping)를, 구성 세부 정보는 [AWS CloudTrail 문서](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/)를 참조하세요.
### 요청 ID
각 응답의 응답 헤더에는 두 개의 요청 ID가 포함됩니다:
* **AWS 요청 ID(`x-amzn-requestid`):** CloudTrail에 인덱싱되는 기본 ID입니다. AWS 도구를 통해 요청을 조사하거나 AWS 지원팀에 문의할 때 사용하세요.
* **Anthropic 요청 ID(`request-id`):** 보조 ID입니다. Anthropic 지원팀에 문의할 때 사용하세요.
```bash cURL
# URL과 --aws-sigv4 모두에서 us-west-2를 사용 중인 AWS 리전으로 바꾸세요
# -i는 출력에 응답 헤더를 포함합니다
# 장기 IAM 사용자 자격 증명을 사용하는 경우 x-amz-security-token 헤더를 생략하세요
curl -i "https://aws-external-anthropic.us-west-2.api.aws/v1/messages" \
--aws-sigv4 "aws:amz:us-west-2:aws-external-anthropic" \
--user "$AWS_ACCESS_KEY_ID:$AWS_SECRET_ACCESS_KEY" \
-H "x-amz-security-token: $AWS_SESSION_TOKEN" \
-H "content-type: application/json" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-workspace-id: $ANTHROPIC_AWS_WORKSPACE_ID" \
-d '{
"model": "claude-sonnet-5-5",
"max_tokens": 1024,
"messages": [
{"role": "user", "content": "Hello!"}
]
}'
```
```bash CLI
# us-west-2를 사용 중인 AWS 리전으로 바꾸세요
# ant는 ANTHROPIC_API_KEY를 읽습니다. AWS Console에서 키를 생성하세요
# (API 키 인증을 참조하세요).
export ANTHROPIC_API_KEY="YOUR_AWS_API_KEY"
# --debug는 X-Amzn-Requestid 및
# Request-Id 헤더를 포함한 HTTP 응답을 stderr에 출력합니다
ant --debug messages create \
--base-url https://aws-external-anthropic.us-west-2.api.aws \
--workspace-id "$ANTHROPIC_AWS_WORKSPACE_ID" \
--model claude-sonnet-5-5 \
--max-tokens 1024 \
--message '{role: user, content: "Hello!"}'
```
```python Python
from anthropic import AnthropicAWS
client = AnthropicAWS()
response = client.messages.with_raw_response.create(
model="claude-sonnet-5-5",
max_tokens=1024,
messages=[{"role": "user", "content": "Hello!"}],
)
print(response.headers.get("x-amzn-requestid")) # AWS request ID
print(response.headers.get("request-id")) # Anthropic request ID
message = response.parse()
print(message.content)
```
```typescript TypeScript
import AnthropicAws from "@anthropic-ai/aws-sdk";
const client = new AnthropicAws();
const { data: message, response } = await client.messages
.create({
model: "claude-sonnet-5-5",
max_tokens: 1024,
messages: [{ role: "user", content: "Hello!" }]
})
.withResponse();
console.log(response.headers.get("x-amzn-requestid")); // AWS request ID
console.log(response.headers.get("request-id")); // Anthropic request ID
console.log(message.content);
```
```csharp C#
using Anthropic;
using Anthropic.Aws;
var client = new AnthropicAwsClient();
var response = await client.WithRawResponse.Messages.Create(new()
{
Model = Model.ClaudeSonnet5_5,
MaxTokens = 1024,
Messages = [new UserMessageParam { Content = "Hello!" }]
});
Console.WriteLine(response.Headers.GetValues("x-amzn-requestid").First()); // AWS request ID
Console.WriteLine(response.Headers.GetValues("request-id").First()); // Anthropic request ID
Console.WriteLine(response.Value.Content);
```
```go Go
client, err := anthropicaws.NewClient(context.Background(), anthropicaws.ClientConfig{})
if err != nil {
panic(err)
}
var response *http.Response
message, err := client.Messages.New(
context.Background(),
anthropic.MessageNewParams{
Model: anthropic.ModelClaudeSonnet5_5,
MaxTokens: 1024,
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("Hello!")),
},
},
option.WithResponseInto(&response),
)
if err != nil {
panic(err)
}
fmt.Println(response.Header.Get("x-amzn-requestid")) // AWS request ID
fmt.Println(response.Header.Get("request-id")) // Anthropic request ID
fmt.Println(message.Content)
```
```java Java
import com.anthropic.aws.backends.AwsBackend;
import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.core.http.HttpResponseFor;
import com.anthropic.models.messages.Message;
import com.anthropic.models.messages.MessageCreateParams;
import com.anthropic.models.messages.Model;
void main() {
AnthropicClient client = AnthropicOkHttpClient.builder()
.backend(AwsBackend.fromEnv())
.build();
HttpResponseFor response = client.messages().withRawResponse().create(
MessageCreateParams.builder()
.model(Model.CLAUDE_SONNET_5_5)
.maxTokens(1024)
.addUserMessage("Hello!")
.build()
);
IO.println(response.headers().values("x-amzn-requestid").get(0)); // AWS request ID
IO.println(response.requestId().orElse(null)); // Anthropic request ID
IO.println(response.parse().content());
}
```
```php PHP
use Anthropic\Aws\Client;
$client = new Client();
$response = $client->messages->raw->create(
model: 'claude-sonnet-5-5',
maxTokens: 1024,
messages: [['role' => 'user', 'content' => 'Hello!']],
);
echo $response->getHeaderLine('x-amzn-requestid') . "\n"; // AWS request ID
echo $response->getHeaderLine('request-id') . "\n"; // Anthropic request ID
echo $response->parse()->content;
```
```ruby Ruby
require "anthropic"
client = Anthropic::AWSClient.new
# 요청별 미들웨어에서 응답 헤더를 읽습니다. 미들웨어는 SDK가 파싱하기 전의
# 원시 HTTP 응답을 받습니다
aws_request_id = nil
anthropic_request_id = nil
read_request_ids = lambda do |request, call_next|
response = call_next.call(request)
# response.headers의 키는 소문자입니다
aws_request_id = response.headers["x-amzn-requestid"]
anthropic_request_id = response.headers["request-id"]
response
end
message = client.messages.create(
model: "claude-sonnet-5-5",
max_tokens: 1024,
messages: [{ role: "user", content: "Hello!" }],
request_options: { middleware: [read_request_ids] }
)
puts aws_request_id # AWS request ID
puts anthropic_request_id # Anthropic request ID
puts message.content
```
Anthropic은 사용 패턴을 파악하고 문제를 조사할 수 있도록 최소 30일 롤링 기준으로 활동을 로깅할 것을 권장합니다.
AWS CloudTrail은 사용자의 AWS 계정 내에서 구성됩니다. 로깅을 활성화해도 청구 및 서비스 운영에 필요한 범위를 넘어 AWS나 Anthropic이 사용자의 콘텐츠에 액세스할 수 있게 되지는 않습니다.
## Amazon Bedrock에서 마이그레이션하기
현재 Bedrock에서 Claude를 사용하고 있다면, Claude Platform on AWS로 마이그레이션하려면 통합 전반에 걸쳐 변경이 필요합니다. SigV4 서명은 계속 지원되지만 서명 컨텍스트, 기본 URL, API 형식, 모델 ID, SDK 클라이언트 및 패키지, 스트리밍 형식, 요청 헤더, 리전 가용성이 모두 변경됩니다. Claude Platform on AWS는 새로운 Anthropic 조직도 프로비저닝합니다. 다음 표에 차이점이 요약되어 있습니다.
### 변경 사항
마이그레이션 차이는 어떤 Bedrock 통합에서 전환하는지에 따라 달라집니다. 다음 표는 [현재 Bedrock 통합](https://platform.claude.com/docs/ko/build-with-claude/claude-in-amazon-bedrock)(`bedrock-mantle.{region}.api.aws`의 Messages API)과 [레거시 InvokeModel 통합](https://platform.claude.com/docs/ko/build-with-claude/claude-on-amazon-bedrock-legacy)을 모두 보여줍니다.
| 항목 | [Claude in Amazon Bedrock](https://platform.claude.com/docs/ko/build-with-claude/claude-in-amazon-bedrock)에서 | [Amazon Bedrock(Opus 4.6 이하)](https://platform.claude.com/docs/ko/build-with-claude/claude-on-amazon-bedrock-legacy)에서 | Claude Platform on AWS로 |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **기본 URL** | `bedrock-mantle.{region}.api.aws` | `bedrock-runtime.{region}.amazonaws.com` | `aws-external-anthropic.{region}.api.aws` |
| **API 형식** | `/anthropic/v1/messages`의 Messages API | Bedrock Converse / InvokeModel | Claude API(`/v1/{endpoint}`) |
| **모델 ID** | anthropic.claude-haiku-4-5 | anthropic.claude-haiku-4-5-20251001-v1:0(`us.` 또는 `global.` 추론 프로필 접두사 포함) | claude-haiku-4-5 |
| **SDK 클라이언트** | `AnthropicBedrockMantle` | `AnthropicBedrock` / Bedrock SDK | 플랫폼 전용 클라이언트([SDK 설치하기](https://platform.claude.com/docs/ko/build-with-claude/claude-platform-on-aws#install-an-sdk) 참조), 베타 |
| **SDK 패키지** | `anthropic[bedrock]` (typescript: `@anthropic-ai/bedrock-sdk`; csharp: `Anthropic.Bedrock`; go: `github.com/anthropics/anthropic-sdk-go/bedrock`; java: `com.anthropic:anthropic-java-bedrock`; php: `anthropic-ai/sdk`; ruby: `anthropic`) | `anthropic[bedrock]` (typescript: `@anthropic-ai/bedrock-sdk`; csharp: `Anthropic.Bedrock`; go: `github.com/anthropics/anthropic-sdk-go/bedrock`; java: `com.anthropic:anthropic-java-bedrock`; php: `anthropic-ai/sdk`; ruby: `anthropic`) 또는 AWS SDK | `anthropic[aws]` (typescript: `@anthropic-ai/aws-sdk`; csharp: `Anthropic.Aws`; go: `github.com/anthropics/anthropic-sdk-go/aws`; java: `com.anthropic:anthropic-java-aws`; php: `anthropic-ai/sdk`; ruby: `anthropic`)([SDK 설치하기](https://platform.claude.com/docs/ko/build-with-claude/claude-platform-on-aws#install-an-sdk) 참조) |
| **SigV4 서비스 이름** | `bedrock-mantle` | `bedrock` | `aws-external-anthropic` |
| **스트리밍 형식** | SSE | AWS EventStream | SSE(Claude API와 동일) |
| **워크스페이스 헤더** | 해당 없음 | 해당 없음 | `anthropic-workspace-id`, 추론 및 리소스 요청에 필수 |
| **리전 가용성** | [Amazon Bedrock 리전](https://docs.aws.amazon.com/bedrock/latest/userguide/bedrock-regions.html) 참조 | [Amazon Bedrock 리전](https://docs.aws.amazon.com/bedrock/latest/userguide/bedrock-regions.html) 참조 | 모든 AWS 상용 리전 |
| **Anthropic 조직** | 필요 없음 | 필요 없음 | 가입 시 새 조직 생성. 기존 조직은 전환할 수 없음([기존 Anthropic 조직에서 이전하기](https://platform.claude.com/docs/ko/build-with-claude/claude-platform-on-aws#moving-from-an-existing-anthropic-organization) 참조) |
현재 Bedrock 통합을 사용 중이라면 요청 본문 형식은 이미 Messages API입니다. 변경 사항은 기본 URL, SigV4 서비스 이름, 모델 ID, 그리고 `anthropic-workspace-id` 헤더 추가입니다. 레거시 InvokeModel 또는 Converse API를 사용 중이라면 요청 및 응답 구조도 Messages API 형식으로 다시 작성해야 합니다. 요청 구조 매핑은 [Claude on Amazon Bedrock(Opus 4.6 이하)](https://platform.claude.com/docs/ko/build-with-claude/claude-on-amazon-bedrock-legacy)을 참조하세요.
### 얻을 수 있는 이점
* 일반적으로 새 모델과 기능에 당일 액세스 가능([기능 제한 사항](https://platform.claude.com/docs/ko/build-with-claude/claude-platform-on-aws#features-not-supported) 참조)
* 문서 생성(PowerPoint, Excel, Word, PDF)을 위한 Agent Skills
* Anthropic 관리형 샌드박스에서의 코드 실행
* `anthropic-beta` 헤더를 통해 Amazon Bedrock에서 제공하지 않는 Claude API 베타 기능 사용([기능 제한 사항](https://platform.claude.com/docs/ko/build-with-claude/claude-platform-on-aws#features-not-supported) 참조)
* 할당량 확인 및 사용량 분석을 위한 Claude Console
* Anthropic 직접 지원
* SigV4의 대안으로서의 API 키 인증([API 키 인증](https://platform.claude.com/docs/ko/build-with-claude/claude-platform-on-aws#api-key-authentication) 참조)
### 동일하게 유지되는 사항
* AWS IAM 인증(SigV4)
* 청구 주체로서의 AWS. 청구 채널은 네이티브 AWS 서비스에서 AWS Marketplace로 변경됩니다([상업적 고려 사항](https://platform.claude.com/docs/ko/build-with-claude/claude-platform-on-aws#commercial-considerations) 참조).
* AWS 약정 소진
### 마이그레이션 시 주의 사항
**먼저 아웃바운드 웹 ID 페더레이션을 활성화하세요.** AWS 계정에서 이전에 Claude Platform on AWS를 사용한 적이 없다면, 요청을 보내기 전에 계정당 한 번 [아웃바운드 웹 ID 페더레이션을 활성화](https://platform.claude.com/docs/ko/build-with-claude/claude-platform-on-aws#enable-outbound-web-identity-federation)해야 합니다. 이 단계를 거치지 않으면 모든 요청이 페더레이션 오류와 함께 실패합니다(정확한 오류와 해결 방법은 [아웃바운드 웹 ID 페더레이션 활성화하기](https://platform.claude.com/docs/ko/build-with-claude/claude-platform-on-aws#enable-outbound-web-identity-federation) 참조). 이 단계는 Bedrock에서는 필요하지 않습니다.
**Claude Platform on AWS에서 Zero Data Retention(ZDR)은 옵트인 방식입니다.** Bedrock에서는 AWS가 데이터 처리자이며 Anthropic은 추론 입력이나 출력을 보존하지 않습니다. Anthropic의 ZDR 프로그램은 그곳에 적용되지 않습니다. Claude Platform on AWS에서는 Anthropic이 독립적인 데이터 처리자로서 추론 데이터를 처리하며, ZDR은 퍼스트 파티 Claude API 모델을 따릅니다. 즉, Anthropic 계정 담당자를 통해 요청하면 사용할 수 있습니다. 데이터 보존 보장에 의존하는 프로덕션 워크로드를 마이그레이션하기 전에 ZDR 등록 여부를 확인하세요.
### 상업적 고려 사항
* **Anthropic 서비스 약관:** Claude Platform on AWS를 사용하려면 Anthropic의 상업 서비스 약관 및 사용 정책에 동의해야 합니다. 조직에서 아직 이에 동의하지 않았다면(예: Bedrock을 통해서만 Claude를 사용한 경우) 계정 설정 중에 동의하라는 메시지가 표시됩니다. [계정 설정하기](https://platform.claude.com/docs/ko/build-with-claude/claude-platform-on-aws#set-up-your-account)를 참조하세요.
* **할인 및 비공개 오퍼:** 협상된 할인과 AWS Marketplace 비공개 오퍼는 Bedrock과 Claude Platform on AWS 간에 자동으로 이전되지 않습니다. Claude Platform on AWS에 대한 상업 조건을 설정하려면 Anthropic 계정 담당자와 협의하세요.
## IAM 정책
Claude Platform on AWS는 액세스 제어를 위해 AWS IAM과 통합됩니다. 표준 IAM 정책 구문을 사용하여 특정 워크스페이스의 특정 API 작업에 대한 액세스를 허용하거나 거부합니다.
SigV4 서비스 이름 및 IAM 작업 네임스페이스는 `aws-external-anthropic`입니다. 작업은 `aws-external-anthropic:` 패턴을 따릅니다(예: `aws-external-anthropic:CreateInference`).
### 예시: 배치 추론 거부
다음 정책은 배치 처리를 차단하면서 실시간 추론을 허용합니다:
```json
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"aws-external-anthropic:CreateInference",
"aws-external-anthropic:CountTokens",
"aws-external-anthropic:GetModel",
"aws-external-anthropic:ListModels",
"aws-external-anthropic:GetWorkspace"
],
"Resource": "arn:aws:aws-external-anthropic:*:*:workspace/*"
},
{
"Effect": "Allow",
"Action": "aws-external-anthropic:ListWorkspaces",
"Resource": "*"
},
{
"Effect": "Deny",
"Action": [
"aws-external-anthropic:CreateBatchInference",
"aws-external-anthropic:GetBatchInference",
"aws-external-anthropic:ListBatchInferences"
],
"Resource": "*"
}
]
}
```
`GetBatchInference` 작업은 배치 메타데이터 경로와 배치 결과 경로를 모두 승인합니다. 이를 거부하면 두 읽기 작업이 모두 차단됩니다. ZDR에 민감한 워크로드에 적합한 Deny 전용 정책은 [ZDR에 민감한 워크스페이스의 기능 잠금](https://platform.claude.com/docs/ko/api/claude-platform-on-aws-iam-actions#feature-lockdown-for-a-zdr-sensitive-workspace)을 참조하세요.
`ListWorkspaces`는 계정 범위 작업이므로 `"Resource": "*"`가 포함된 별도의 Allow 문에 나타납니다. 계정 범위 작업에 워크스페이스 ARN을 지정해도 효과가 없습니다([프로비저닝 자동화](https://platform.claude.com/docs/ko/api/claude-platform-on-aws-iam-actions#provisioning-automation) 참조).
이 정책은 AWS SigV4 인증을 가정합니다. 주체가 API 키로 인증하는 경우 `"Resource": "*"` Allow 문에 `aws-external-anthropic:CallWithBearerToken`도 추가하세요. `CallWithBearerToken`은 워크스페이스 ARN에 바인딩되지 않는, 경로가 없는 인증 계층 작업입니다. 두 개의 문을 사용하는 패턴은 [고객별 워크스페이스 격리](https://platform.claude.com/docs/ko/api/claude-platform-on-aws-iam-actions#per-customer-workspace-isolation)를 참조하세요.
### 관리형 정책
AWS는 일반적인 액세스 패턴을 위해 다섯 가지 관리형 정책(`AnthropicFullAccess`, `AnthropicReadOnlyAccess`, `AnthropicInferenceAccess`, `AnthropicLimitedAccess`, `AnthropicSelfHostedEnvironmentAccess`)을 제공합니다. 각 정책이 부여하는 작업, 전체 IAM 작업 목록, 경로-작업 매핑, 추가 정책 예시는 [Claude Platform on AWS용 IAM 작업](https://platform.claude.com/docs/ko/api/claude-platform-on-aws-iam-actions#managed-policies)을 참조하세요.
## 다음 단계
Claude의 고급 기능과 역량을 살펴보세요.
Claude Platform on AWS 가격과 Claude Consumption Unit 요금에 대해 알아보세요.
더 안전하고 뛰어난 모델이 출시됨에 따라 Anthropic은 정기적으로 이전 모델을 종료합니다. 모든 API 지원 중단 내역과 권장 대체 모델을 확인하세요.
## 추가 리소스
Claude Console에서 사용량, 비용, 워크스페이스를 확인하세요. AWS Console을 통해 로그인합니다.
AWS를 유일한 데이터 처리자로 두어야 하는 경우 AWS가 운영하는 Claude를 사용하세요.
AWS Marketplace 구독과 청구를 관리하세요.