워크스페이스

워크스페이스는 조직 내에서 API 사용을 구성하는 방법을 제공합니다. 워크스페이스를 사용하면 중앙 집중식 청구 및 관리를 유지하면서 서로 다른 프로젝트, 환경 또는 팀을 분리할 수 있습니다.

워크스페이스 작동 방식

모든 조직에는 이름을 변경하거나, 보관하거나, 삭제할 수 없는 Default Workspace(기본 워크스페이스)가 있습니다. 추가 워크스페이스를 생성하면 각 워크스페이스에 멤버, 서비스 계정, API 키 및 리소스 제한을 할당할 수 있습니다.

주요 특징:

• 워크스페이스 식별자는 wrkspc_ 접두사를 사용합니다(예: wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ)
• 기본적으로 조직당 최대 100개의 워크스페이스를 가질 수 있습니다(보관된 워크스페이스는 포함되지 않음). 더 필요한 경우 계정 팀에 문의하세요
• Default Workspace는 다른 워크스페이스와 마찬가지로 wrkspc_ ID를 가지지만(anthropic-workspace-id 응답 헤더로 반환되고 Get Workspace에서 허용됨), List Workspaces 결과에는 나타나지 않으며, API 키, 사용량 보고서 및 비용 보고서에서는 workspace_id가 null로 표시됩니다. 모든 워크스페이스에 걸친 API 키도 마찬가지입니다(API 키의 scope 필드로 이 둘을 구분할 수 있으며, Default Workspace에 바인딩된 키의 경우 실제 ID를 담고 있습니다)
• API 키는 단일 워크스페이스로 범위를 지정할 수 있습니다. 이 경우 해당 워크스페이스 내의 리소스에만 액세스할 수 있습니다. 일부 API 키는 여러 워크스페이스에 걸친 권한을 부여받을 수 있으며, 워크스페이스 ID 헤더를 제공하여 해당 워크스페이스 내의 리소스에 액세스합니다

Claude Code 워크스페이스

조직의 멤버가 Claude Console 계정으로 Claude Code에 처음 로그인하면, Anthropic은 조직에 Claude Code 워크스페이스를 자동으로 생성하고 해당 멤버를 추가합니다. 이후 Claude Code에 로그인하는 모든 멤버도 같은 방식으로 추가됩니다.

Claude Code 워크스페이스는 Claude Code 트래픽을 다른 API 워크로드와 분리하여 유지합니다:

• Claude Code는 로그인 시 이 워크스페이스에서 사용자별 API 키를 발급합니다. Console에서 수동으로 이 워크스페이스에 키를 생성할 수는 없습니다.
• Claude Code 키는 워크스페이스 키와 달리 소유자가 워크스페이스 또는 조직에서 제거되면 작동을 멈춥니다.
• Claude Code 사용량은 별도로 속도 제한이 적용되며, 관리자는 Settings > Workspaces에서 조직 제한 중 Claude Code가 차지하는 비율에 상한을 설정할 수 있습니다.
• 사용자별 월간 지출 한도를 지원하는 유일한 워크스페이스입니다.

워크스페이스 역할 및 권한

멤버는 각 워크스페이스에서 서로 다른 역할을 가질 수 있어 세밀한 액세스 제어가 가능합니다.

역할 상속

• 조직 관리자는 모든 워크스페이스에 대한 Workspace Admin 액세스를 자동으로 받습니다
• 조직 청구 멤버는 모든 워크스페이스에 대한 Workspace Billing 액세스를 자동으로 받습니다
• 조직 사용자 및 개발자는 각 워크스페이스에 명시적으로 추가되어야 합니다
• 서비스 계정은 Settings → Service accounts의 서비스 계정 페이지 또는 워크스페이스의 Service accounts 탭에서 워크스페이스에 추가됩니다

워크스페이스 관리

Console 사용

Claude Console에서 워크스페이스를 생성하고 관리하세요.

워크스페이스 생성

1. 1

   워크스페이스 설정 열기

   Claude Console에서 Settings > Workspaces로 이동하세요.

2. 2

   워크스페이스 생성

   Create workspace를 클릭하세요.

3. 3

   워크스페이스 구성

   워크스페이스 이름을 입력하고 시각적 식별을 위한 색상을 선택하세요.

4. 4

   워크스페이스 생성 완료

   Create를 클릭하여 완료하세요.

워크스페이스 세부 정보 편집

워크스페이스의 이름이나 색상을 수정하려면:

1. 목록에서 워크스페이스를 선택하세요.
2. 줄임표 메뉴(...)를 클릭하고 Edit details를 선택하세요.
3. 이름이나 색상을 업데이트하고 변경 사항을 저장하세요.

워크스페이스에 멤버 추가

1. 워크스페이스의 Members 탭으로 이동하세요.
2. Add to Workspace를 클릭하세요.
3. 조직 멤버를 선택하고 워크스페이스 역할을 할당하세요.
4. 추가를 확인하세요.

멤버를 제거하려면 이름 옆의 휴지통 아이콘을 클릭하세요.

워크스페이스 제한 설정

각 워크스페이스의 설정은 이를 두 개의 탭으로 나눕니다:

• 속도 제한: Rate limits 탭에서 모델 티어별로 분당 요청 수, 입력 토큰 또는 출력 토큰에 대한 제한을 설정하세요
• 지출 한도: Spend limits 탭에서 월간 지출에 상한을 설정하고 지출이 특정 임계값에 도달할 때 알림을 구성하세요

워크스페이스 보관

워크스페이스를 보관하려면 줄임표 메뉴(...)를 클릭하고 Archive를 선택하세요. 보관하면:

• 보고를 위한 과거 데이터가 보존됩니다
• 워크스페이스가 비활성화되고 해당 워크스페이스용으로 생성된 모든 API 키가 보관됩니다
• 되돌릴 수 없습니다

Admin API 사용

Admin API를 사용하여 프로그래밍 방식으로 워크스페이스를 관리하세요.

다음 SDK 및 CLI 예제는 ANTHROPIC_API_KEY 환경 변수에서 Admin API 키를 읽는 기본 클라이언트를 구성합니다. SDK는 이러한 엔드포인트를 client.beta.organization.workspaces 아래에 노출합니다. SDK 목록 메서드는 필요에 따라 추가 페이지를 가져오므로 limit은 페이지 크기를 설정합니다. PHP, Ruby 및 curl 예제는 한 페이지를 반환합니다.

워크스페이스 생성:

client = anthropic.Anthropic()

workspace = client.beta.organization.workspaces.create(name="Production")

print(f"id: {workspace.id}")
print(f"name: {workspace.name}")

워크스페이스 목록 조회:

client = anthropic.Anthropic()

workspaces = client.beta.organization.workspaces.list(limit=10, include_archived=False)

for workspace in workspaces:
    print(f"{workspace.id}: {workspace.name}")

워크스페이스 보관:

client = anthropic.Anthropic()

workspace = client.beta.organization.workspaces.archive(
    "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ"
)

print(f"id: {workspace.id}")
print(f"archived_at: {workspace.archived_at}")

전체 매개변수 세부 정보 및 응답 스키마는 Workspaces API 레퍼런스를 참조하세요.

워크스페이스 멤버 관리

워크스페이스에 멤버 추가:

client = anthropic.Anthropic()

member = client.beta.organization.workspaces.members.add(
    "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ",
    user_id="user_01XyDMpzjS89pFZXqSFUBDr6",
    workspace_role="workspace_developer",
)

print(f"user_id: {member.user_id}")
print(f"workspace_role: {member.workspace_role}")

멤버 역할 업데이트:

client = anthropic.Anthropic()

member = client.beta.organization.workspaces.members.update(
    "user_01XyDMpzjS89pFZXqSFUBDr6",
    workspace_id="wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ",
    workspace_role="workspace_admin",
)

print(f"user_id: {member.user_id}")
print(f"workspace_role: {member.workspace_role}")

워크스페이스에서 멤버 제거:

client = anthropic.Anthropic()

removed_member = client.beta.organization.workspaces.members.remove(
    "user_01XyDMpzjS89pFZXqSFUBDr6",
    workspace_id="wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ",
)

print(f"user_id: {removed_member.user_id}")

전체 매개변수 세부 정보는 Workspace Members API 레퍼런스를 참조하세요.

API 키 및 리소스 범위 지정

모든 요청은 정확히 하나의 워크스페이스에서 실행되며 해당 워크스페이스 내의 리소스에만 액세스할 수 있습니다. 어느 워크스페이스인지는 키 유형에 따라 달라집니다:

• 워크스페이스 키(소유자가 없는 레거시 키)는 생성된 워크스페이스에 속하며 항상 그곳에서 실행됩니다.
• 개인 키 또는 서비스 계정 키는 해당 사용자 또는 서비스 계정으로서 동작합니다. 단일 워크스페이스 키는 항상 생성 시 선택한 워크스페이스에서 실행됩니다. 다중 워크스페이스 키는 각 요청의 anthropic-workspace-id 헤더에 지정된 워크스페이스에서 실행됩니다. 계정이 해당 워크스페이스를 사용하려면 액세스 권한이 있어야 합니다.

워크스페이스로 범위가 지정되는 리소스는 다음과 같습니다:

• Files API를 통해 생성된 파일
• Batch API를 통해 생성된 메시지 배치
• Skills API를 통해 생성된 스킬

일부 리소스는 다르게 관리됩니다:

• **MCP 터널**은 API 키가 아니라 Workload Identity Federation을 통해 얻은 workspace:manage_tunnels OAuth 토큰으로 관리됩니다. 터널은 워크스페이스에 생성되며, Console의 MCP tunnels 목록과 Managed Agent 서버 선택기는 현재 워크스페이스의 터널만 표시합니다. 활성 터널 10개 상한은 조직 전체에 적용됩니다. 터널 관리에는 터널 관리 권한이 있는 역할이 필요하며, 조직 개발자는 볼 수는 있지만 변경할 수는 없습니다.
• 워크스페이스 자체와 조직 멤버는 Admin API 키, org:admin OAuth 토큰, 또는 특정 워크스페이스로 범위가 지정되지 않은 개인 또는 서비스 계정 키를 사용하여 Admin API를 통해 조직 수준에서 관리됩니다.

조직의 워크스페이스 ID를 조회하려면 List Workspaces 엔드포인트를 호출하거나 Claude Console에서 찾으세요.

API 응답의 워크스페이스 식별

Claude API 응답에는 request-id 및 anthropic-organization-id 응답 헤더와 함께 anthropic-workspace-id 헤더가 포함됩니다. 그 값은 요청의 API 키 또는 액세스 토큰이 확인된 워크스페이스의 wrkspc_ 접두사 ID이며, 해당 워크스페이스가 Default Workspace인 경우도 포함됩니다. 예를 들어, 성공적인 응답에는 다음과 같은 헤더가 포함됩니다:

HTTP/1.1 200 OK
request-id: req_018EeWyXxfu5pfWkrYcMdjWG
anthropic-organization-id: 0d0e7a3b-52f1-4c7e-9a51-3f6f2f7c1b9e
anthropic-workspace-id: wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ

자격 증명이 워크스페이스로 확인되지 않는 경우(예: Admin API 요청) 또는 401 오류와 같이 인증이 완료되기 전에 요청이 실패하는 경우에는 이 헤더가 없습니다.

다음 예제는 Messages API 요청을 보내고 응답 헤더에서 워크스페이스 ID를 출력합니다:

client = anthropic.Anthropic()

response = client.messages.with_raw_response.create(
    model="claude-opus-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)
workspace_id = response.headers.get("anthropic-workspace-id")
print(f"Workspace ID: {workspace_id}")

Workspace ID: wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ

동일한 접근자로 Claude Managed Agents API를 포함한 다른 Claude API 엔드포인트에서도 이 헤더를 읽을 수 있습니다. 예를 들어, 세션을 생성하는 응답에서 anthropic-workspace-id를 읽어 세션이 어느 워크스페이스에 속하는지 기록할 수 있습니다.

응답에서 얻은 워크스페이스 ID로 다음을 수행할 수 있습니다:

• 요청이 어느 워크스페이스의 사용량, 비용 및 속도 제한에 집계되었는지 확인
• Usage and Cost API 보고서 및 API 키와 같은 Admin API 객체의 workspace_id 필드와 대조(둘 다 Default Workspace에 대해 null을 보고하며, API 키는 모든 워크스페이스에 걸친 키에 대해서도 null을 보고합니다. API 키의 scope 필드로 이 둘을 구분할 수 있으며, 하나의 워크스페이스에 바인딩된 키의 경우 해당 워크스페이스의 실제 ID를 담고 있습니다)
• Admin API 키로 Get Workspace에 전달하여 Default Workspace의 ID인지 확인: List Workspaces에서는 생략되지만 Default Workspace는 "name": "Default"로 반환됩니다
• Console에서 해당 워크스페이스를 열어 세션, 파일, 메시지 배치, 스킬과 같은 요청의 리소스 찾기

워크스페이스 제한

과도한 사용을 방지하고 공정한 리소스 분배를 보장하기 위해 각 워크스페이스에 사용자 지정 지출 한도 및 속도 제한을 설정할 수 있습니다.

워크스페이스 제한 설정

워크스페이스 제한은 조직의 제한보다 낮게(높게는 불가) 설정할 수 있습니다:

• 지출 한도: 워크스페이스의 월간 지출에 상한을 설정합니다. Claude Console의 워크스페이스 Spend limits 설정 탭에서 설정하세요.
• 속도 제한: 분당 요청 수, 분당 입력 토큰 또는 분당 출력 토큰을 제한합니다. Claude Console의 워크스페이스 Rate limits 설정 탭에서 설정하세요.

속도 제한 및 작동 방식에 대한 자세한 내용은 속도 제한을 참조하세요. Rate Limits API를 사용하여 현재 조직 및 워크스페이스 속도 제한을 프로그래밍 방식으로 읽을 수도 있습니다.

사용량 및 비용 추적

Usage and Cost API를 사용하여 워크스페이스별로 사용량과 비용을 추적하세요:

curl "https://api.anthropic.com/v1/organizations/usage_report/messages?\
starting_at=2025-01-01T00:00:00Z&\
ending_at=2025-01-08T00:00:00Z&\
workspace_ids[]=wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ&\
group_by[]=workspace_id&\
bucket_width=1d" \
  -H "anthropic-version: 2023-06-01" \
  -H "x-api-key: $ANTHROPIC_ADMIN_KEY"

Default Workspace에 귀속된 사용량 및 비용은 workspace_id 값이 null입니다.

일반적인 사용 사례

환경 분리

개발, 스테이징 및 프로덕션을 위한 별도의 워크스페이스를 생성하세요:

팀 또는 부서 격리

비용 할당 및 액세스 제어를 위해 서로 다른 팀에 워크스페이스를 할당하세요:

• 개발자 액세스 권한이 있는 엔지니어링 팀
• 자체 API 키를 가진 데이터 사이언스 팀
• 고객 도구를 위한 제한된 액세스 권한이 있는 지원 팀

프로젝트 기반 구성

특정 프로젝트 또는 제품을 위한 워크스페이스를 생성하여 사용량과 비용을 별도로 추적하세요.

모범 사례

1. 1

   워크스페이스 구조 계획

   워크스페이스를 생성하기 전에 어떻게 구성할지 고려하세요. 청구, 액세스 제어 및 사용량 추적 요구 사항을 생각해 보세요.

2. 2

   의미 있는 이름 사용

   목적을 나타내도록 워크스페이스 이름을 명확하게 지정하세요(예: "Production - Customer Chatbot" 또는 "Dev - Internal Tools").

3. 3

   적절한 제한 설정

   예상치 못한 비용을 방지하고 공정한 리소스 분배를 보장하기 위해 지출 한도 및 속도 제한을 구성하세요.

4. 4

   정기적으로 액세스 감사

   적절한 사용자만 액세스할 수 있도록 워크스페이스 멤버십을 주기적으로 검토하세요.

5. 5

   사용량 모니터링

   Usage and Cost API를 사용하여 워크스페이스 수준의 소비를 추적하세요.

FAQ

참고 항목

• Admin API
• Admin API 레퍼런스
• 속도 제한
• Usage and Cost API