워크스페이스

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

워크스페이스 작동 방식

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

주요 특징:

• 워크스페이스 식별자는 wrkspc_ 접두사를 사용합니다(예: wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ).
• 기본적으로 조직당 최대 100개의 워크스페이스를 가질 수 있습니다(보관된 워크스페이스는 포함되지 않음). 더 필요한 경우 계정 팀에 문의하세요.
• 기본 워크스페이스는 다른 워크스페이스와 마찬가지로 wrkspc_ ID를 가지지만(anthropic-workspace-id 응답 헤더로 반환되며 워크스페이스 조회API 참조 링크가 포함된 미리보기 사용 가능 — 카드에 포커스가 들어올 때까지 Tab을 누르고, 돌아가려면 Escape를 누르세요.에서 허용됨), 워크스페이스 목록 조회API 참조 링크가 포함된 미리보기 사용 가능 — 카드에 포커스가 들어올 때까지 Tab을 누르고, 돌아가려면 Escape를 누르세요. 결과에는 include_default=true를 전달한 경우에만 나타납니다. Usage and Cost Analytics API는 해당 ID로 사용량과 비용을 보고하는 반면, 레거시 Usage and Cost API 보고서는 workspace_id에 대해 null을 표시합니다(기본 워크스페이스에 바인딩된 키의 경우 API 키의 scope 필드에 실제 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 사용량은 별도로 속도 제한이 적용되며, 관리자는 Claude Console의 속도 제한에서 조직 제한 중 Claude Code가 차지하는 비율에 상한을 설정할 수 있습니다.
• 사용자별 월간 지출 한도를 지원하는 유일한 워크스페이스입니다.

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

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

역할 상속

• 조직 관리자는 모든 워크스페이스에 대한 워크스페이스 관리자 액세스를 자동으로 받습니다.
• 조직 결제 멤버는 모든 워크스페이스에 대한 워크스페이스 결제 액세스를 자동으로 받습니다.
• 조직 사용자 및 개발자는 각 워크스페이스에 명시적으로 추가되어야 합니다.
• 서비스 계정은 Claude Console의 서비스 계정 페이지(platform.claude.com/settings/service-accounts)에서 워크스페이스에 추가됩니다. 계정의 메뉴 또는 계정 자체 페이지에서 워크스페이스에 추가를 선택하세요. 한 워크스페이스의 계정을 보려면 목록을 워크스페이스별로 필터링하세요.

워크스페이스 관리

Console 사용

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

워크스페이스 생성

1. 1

   워크스페이스 설정 열기

   Claude Console에서 워크스페이스 페이지(platform.claude.com/settings/workspaces)로 이동하세요.

2. 2

   워크스페이스 만들기 페이지 열기

   워크스페이스 만들기를 클릭하여 Console에서 워크스페이스 만들기 페이지(platform.claude.com/settings/workspaces/new)를 여세요.

3. 3

   워크스페이스 구성

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

4. 4

   워크스페이스 생성 완료

   워크스페이스 만들기를 클릭하여 완료하세요.

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

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

1. 목록에서 워크스페이스를 선택하세요.
2. 추가 작업 메뉴(점 세 개)를 열고 세부정보 수정을 선택하세요.
3. 이름 또는 색상을 업데이트하고 변경 사항을 저장하세요.

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

1. Claude Console에서 멤버 페이지(platform.claude.com/settings/members)로 이동하세요.
2. 워크스페이스에 추가를 클릭하세요.
3. 워크스페이스, 추가할 조직 멤버 및 해당 멤버의 워크스페이스 역할을 선택하세요.
4. 워크스페이스에 추가를 클릭하여 확인하세요.

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

1. Claude Console의 멤버 페이지에 있는 워크스페이스 드롭다운 메뉴에서 워크스페이스를 선택하세요. 전체로 표시되어 있으면 멤버 제거는 대신 조직에서 멤버를 제거합니다.
2. 멤버 행의 끝에서 추가 작업 메뉴(점 세 개)를 열고 멤버 제거를 선택하세요.
3. 제거를 클릭하여 확인하세요.

워크스페이스 제한 설정

워크스페이스의 속도 제한과 지출 한도는 서로 다른 곳에서 설정합니다:

• 속도 제한: Claude Console의 속도 제한에서 워크스페이스 드롭다운 메뉴로 워크스페이스를 선택하고 모델 옆의 편집을 클릭하여 분당 요청 수, 입력 토큰 또는 출력 토큰에 대한 제한을 설정합니다.
• 지출 한도: Claude Console의 워크스페이스 페이지에서 워크스페이스를 선택하세요. 열리는 패널에서 지출 한도를 클릭하여 월간 지출에 상한을 설정하고 지출이 특정 임계값에 도달할 때의 알림을 구성하세요.

워크스페이스 보관

워크스페이스를 보관하려면 해당 워크스페이스의 추가 작업 메뉴(점 세 개)를 열고 워크스페이스 보관을 선택하세요. 보관하면:

• 보고를 위한 기록 데이터를 보존합니다
• 워크스페이스를 비활성화하고 해당 워크스페이스에 대해 생성된 모든 API 키를 보관합니다
• 취소할 수 없습니다

Admin API 사용

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

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

워크스페이스 생성:

client = anthropic.Anthropic()

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

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

워크스페이스 목록:

client = anthropic.Anthropic()

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

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

워크스페이스 보관:

client = anthropic.Anthropic()

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

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

전체 매개변수 세부 정보 및 응답 스키마는 Workspaces API 레퍼런스API 참조 링크가 포함된 미리보기 사용 가능 — 카드에 포커스가 들어올 때까지 Tab을 누르고, 돌아가려면 Escape를 누르세요.를 참조하세요.

워크스페이스 멤버 관리

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

client = anthropic.Anthropic()

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

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

멤버의 역할 업데이트:

client = anthropic.Anthropic()

member = client.organization.workspaces.members.update(
    "user_01WxYzAbCdEfGhJkMnPqRsTu",
    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.organization.workspaces.members.remove(
    "user_01WxYzAbCdEfGhJkMnPqRsTu",
    workspace_id="wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ",
)

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

전체 매개변수 세부 정보는 워크스페이스 멤버 API 레퍼런스API 참조 링크가 포함된 미리보기 사용 가능 — 카드에 포커스가 들어올 때까지 Tab을 누르고, 돌아가려면 Escape를 누르세요.를 참조하세요.

API 키 및 리소스 범위 지정

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

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

워크스페이스로 범위가 지정된 리소스에는 다음이 포함됩니다:

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

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

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

조직의 워크스페이스 ID를 조회하려면 워크스페이스 목록 조회API 참조 링크가 포함된 미리보기 사용 가능 — 카드에 포커스가 들어올 때까지 Tab을 누르고, 돌아가려면 Escape를 누르세요. 엔드포인트를 호출하거나(기본 워크스페이스를 포함하려면 include_default=true를 전달) Claude Console의 워크스페이스 페이지에서 확인하세요.

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

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

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-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 Analytics API 행의 workspace_id 필드(기본 워크스페이스에 대해서도 동일한 ID를 담고 있음) 및 Admin API에서 API 키의 scope 필드(기본 워크스페이스를 포함하여 키가 바인딩된 워크스페이스의 실제 ID를 담고 있음)와 대조
• Admin API 키와 함께 워크스페이스 조회API 참조 링크가 포함된 미리보기 사용 가능 — 카드에 포커스가 들어올 때까지 Tab을 누르고, 돌아가려면 Escape를 누르세요.에 전달하여 기본 워크스페이스의 ID인지 확인: 워크스페이스 목록 조회API 참조 링크가 포함된 미리보기 사용 가능 — 카드에 포커스가 들어올 때까지 Tab을 누르고, 돌아가려면 Escape를 누르세요.는 include_default=true를 전달하지 않으면 기본 워크스페이스를 생략하지만, 기본 워크스페이스는 "name": "Default"로 반환됩니다
• Console에서 해당 워크스페이스를 열어 세션, 파일, 메시지 배치 및 스킬과 같은 요청의 리소스를 찾기

워크스페이스 제한

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

워크스페이스 제한 설정

워크스페이스 제한을 조직의 제한보다 낮게(하지만 높게는 아님) 설정할 수 있습니다:

• 지출 한도: 워크스페이스의 월간 지출에 상한을 설정합니다. 설정하려면 Claude Console의 워크스페이스 페이지(platform.claude.com/settings/workspaces)로 이동하여 워크스페이스를 선택하세요. 열리는 패널에서 지출 한도를 클릭하세요.
• 속도 제한: 분당 요청 수, 분당 입력 토큰 수 또는 분당 출력 토큰 수를 제한합니다. 설정하려면 Claude Console의 속도 제한으로 이동하여 워크스페이스 드롭다운 메뉴에서 워크스페이스를 선택하고 모델 옆의 편집을 클릭하세요.

속도 제한과 그 작동 방식에 대한 자세한 내용은 속도 제한을 참조하세요. 또한 Rate Limits API를 사용하여 현재 조직 및 워크스페이스의 속도 제한을 조회하고 워크스페이스 속도 제한을 프로그래밍 방식으로 설정할 수 있습니다. 이 API는 조직의 한도보다 높은 값도 저장하지만, 실제로는 두 값 중 더 낮은 값을 적용합니다.

사용량 및 비용 추적

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

client = anthropic.Anthropic()

rows = client.beta.organization.analytics.usage.list(
    starting_at="2026-09-01T00:00:00Z",
    ending_at="2026-09-08T00:00:00Z",
    time_bucket_width="1d",
    workspace_ids=["wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ"],
    group_by=["workspace_id"],
)

for row in rows:
    print(f"{row.starting_at} {row.group.workspace_id}: {row.usage.total_tokens}")

기본 워크스페이스의 사용량과 비용은 기본 워크스페이스 자체의 ID로 보고됩니다.

일반적인 사용 사례

환경 분리

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

팀 또는 부서 격리

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

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

프로젝트 기반 조직

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

모범 사례

1. 1

   워크스페이스 구조 계획

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

2. 2

   의미 있는 이름 사용

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

3. 3

   적절한 제한 설정

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

4. 4

   정기적으로 액세스 감사

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

5. 5

   사용량 모니터링

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

자주 묻는 질문

참고 항목

• Admin API
• Admin API 레퍼런스
• 속도 제한
• Usage and Cost Analytics API 및 레거시 Usage and Cost API