워크스페이스

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



워크스페이스 작동 방식

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

주요 특징:

• 워크스페이스 식별자는 wrkspc_ 접두사를 사용합니다(예: wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ)
• 조직당 최대 100개의 워크스페이스(보관된 워크스페이스는 포함되지 않음)
• Default Workspace는 ID가 없으며 목록 엔드포인트에 표시되지 않습니다
• API 키는 단일 워크스페이스로 범위가 지정되며 해당 워크스페이스 내의 리소스에만 액세스할 수 있습니다



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 액세스 권한을 받습니다
• 조직 사용자 및 개발자는 각 워크스페이스에 명시적으로 추가되어야 합니다



워크스페이스 관리



Console 사용

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



워크스페이스 생성



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

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

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



워크스페이스에 멤버 추가

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

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



워크스페이스 제한 설정

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

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



워크스페이스 보관

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

• 보고를 위한 과거 데이터가 보존됩니다
• 워크스페이스 및 연결된 모든 API 키가 비활성화됩니다
• 되돌릴 수 없습니다



Admin API 사용

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

# 워크스페이스 생성
curl -X POST "https://api.anthropic.com/v1/organizations/workspaces" \
  -H "anthropic-version: 2023-06-01" \
  -H "x-api-key: $ANTHROPIC_ADMIN_KEY" \
  -d '{"name": "Production"}'

# 워크스페이스 목록 조회
curl "https://api.anthropic.com/v1/organizations/workspaces?limit=10&include_archived=false" \
  -H "anthropic-version: 2023-06-01" \
  -H "x-api-key: $ANTHROPIC_ADMIN_KEY"

# 워크스페이스 보관
curl -X POST "https://api.anthropic.com/v1/organizations/workspaces/{workspace_id}/archive" \
  -H "anthropic-version: 2023-06-01" \
  -H "x-api-key: $ANTHROPIC_ADMIN_KEY"

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



워크스페이스 멤버 관리

워크스페이스에서 멤버를 추가, 업데이트 또는 제거하세요:

# 워크스페이스에 멤버 추가
curl -X POST "https://api.anthropic.com/v1/organizations/workspaces/{workspace_id}/members" \
  -H "anthropic-version: 2023-06-01" \
  -H "x-api-key: $ANTHROPIC_ADMIN_KEY" \
  -d '{
    "user_id": "user_xxx",
    "workspace_role": "workspace_developer"
  }'

# 멤버의 역할 업데이트
curl -X POST "https://api.anthropic.com/v1/organizations/workspaces/{workspace_id}/members/{user_id}" \
  -H "anthropic-version: 2023-06-01" \
  -H "x-api-key: $ANTHROPIC_ADMIN_KEY" \
  -d '{"workspace_role": "workspace_admin"}'

# 워크스페이스에서 멤버 제거
curl -X DELETE "https://api.anthropic.com/v1/organizations/workspaces/{workspace_id}/members/{user_id}" \
  -H "anthropic-version: 2023-06-01" \
  -H "x-api-key: $ANTHROPIC_ADMIN_KEY"

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



API 키 및 리소스 범위 지정

API 키는 특정 워크스페이스로 범위가 지정됩니다. 워크스페이스에서 API 키를 생성하면 해당 워크스페이스 내의 리소스에만 액세스할 수 있습니다.

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

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

일부 리소스는 워크스페이스 API 키로 관리할 수 없습니다:

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



워크스페이스 제한

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



워크스페이스 제한 설정

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

• 지출 한도: 워크스페이스의 월간 지출을 제한합니다. 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 키를 보유한 데이터 사이언스 팀
• 고객 도구에 대한 제한된 액세스 권한이 있는 지원 팀



프로젝트 기반 구성

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



모범 사례



FAQ



참고 항목

• Admin API
• Admin API 참조
• 속도 제한
• Usage and Cost API