Workspaces

Os workspaces fornecem uma maneira de organizar o uso da sua API dentro de uma organização. Use workspaces para separar diferentes projetos, ambientes ou equipes, mantendo o faturamento e a administração centralizados.

Como os workspaces funcionam

Toda organização tem um workspace padrão que não pode ser renomeado, arquivado ou excluído. Quando você cria workspaces adicionais, pode atribuir membros, contas de serviço, chaves de API e limites de recursos a cada um.

Características principais:

• Identificadores de workspace usam o prefixo wrkspc_ (por exemplo, wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ).
• Máximo de 100 workspaces por organização por padrão (workspaces arquivados não contam). Entre em contato com sua equipe de conta se precisar de mais.
• O workspace padrão tem um ID wrkspc_ como qualquer outro workspace (retornado no cabeçalho de resposta anthropic-workspace-id e aceito por Obter workspacePré-visualização disponível com links para a referência da API — pressione Tab até o foco entrar no cartão, Escape para voltar.), mas aparece nos resultados de Listar workspacesPré-visualização disponível com links para a referência da API — pressione Tab até o foco entrar no cartão, Escape para voltar. somente quando você passa include_default=true. A API de Análise de Uso e Custo informa seu uso e custo sob esse ID, enquanto os relatórios da API de Uso e Custo legada mostram null para seu workspace_id (o campo scope de uma chave de API contém o ID real para uma chave vinculada ao workspace padrão).
• Chaves de API podem ter escopo de um único workspace. Nesse caso, elas só podem acessar recursos dentro desse workspace. Outras chaves de API não têm escopo de workspace. Com uma dessas chaves, envie um cabeçalho de ID de workspace em cada solicitação para escolher o workspace. O usuário ou a conta de serviço da chave deve ter acesso a esse workspace.

Workspace do Claude Code

Quando um membro da sua organização faz login pela primeira vez no Claude Code com sua conta do Claude Console, a Anthropic cria automaticamente um workspace Claude Code na organização e adiciona esse membro a ele. Todo membro subsequente que faz login no Claude Code é adicionado da mesma forma.

O workspace do Claude Code mantém o tráfego do Claude Code separado das suas outras cargas de trabalho da API:

• O Claude Code gera uma chave de API por usuário neste workspace no momento do login. Você não pode criar chaves nele manualmente pelo Console.
• Uma chave do Claude Code para de funcionar se seu proprietário for removido do workspace ou da organização, ao contrário de uma chave de workspace.
• O uso do Claude Code tem limite de taxa separado, e os administradores podem limitar sua parcela dos limites da organização em Limites de taxa no Claude Console.
• É o único workspace que suporta limites de gasto mensal por usuário.

Funções e permissões de workspace

Os membros podem ter funções diferentes em cada workspace, permitindo controle de acesso granular.

Herança de funções

• Administradores da organização recebem automaticamente acesso de Administrador do workspace a todos os workspaces.
• Membros de faturamento da organização recebem automaticamente acesso de Faturamento do workspace a todos os workspaces.
• Usuários e desenvolvedores da organização devem ser adicionados explicitamente a cada workspace.
• Contas de serviço são adicionadas a workspaces na página Contas de serviço (platform.claude.com/settings/service-accounts) no Claude Console: selecione Adicionar ao espaço de trabalho no menu da conta ou na própria página dela. Para ver as contas de um workspace, filtre a lista por workspace.

Gerenciando workspaces

Usando o Console

Crie e gerencie workspaces na página Espaços de trabalho no Claude Console.

Criar um workspace

1. 1

   Abra as configurações de workspace

   No Claude Console, acesse a página Espaços de trabalho (platform.claude.com/settings/workspaces).

2. 2

   Abra a página Criar workspace

   Clique em Criar workspace para abrir a página Criar workspace (platform.claude.com/settings/workspaces/new) no Console.

3. 3

   Configure o workspace

   Insira um nome para o workspace e selecione uma cor para identificação visual.

4. 4

   Crie o workspace

   Clique em Criar workspace para finalizar.

Editar detalhes do workspace

Para modificar o nome ou a cor de um workspace:

1. Selecione o workspace na lista.
2. Abra o menu Mais ações (três pontos) e selecione Editar detalhes.
3. Atualize o nome ou a cor e salve suas alterações.

Adicionar membros a um workspace

1. No Claude Console, acesse a página Membros (platform.claude.com/settings/members).
2. Clique em Adicionar ao espaço de trabalho.
3. Selecione o workspace, o membro da organização a ser adicionado e sua função de workspace.
4. Clique em Adicionar ao espaço de trabalho para confirmar.

Remover membros de um workspace

1. Na página Membros no Claude Console, selecione o workspace no menu suspenso Espaço de trabalho. Se ele mostrar Todos, Remover membro remove o membro da sua organização, e não apenas do workspace.
2. No final da linha do membro, abra o menu Mais ações (três pontos) e selecione Remover membro.
3. Clique em Remover para confirmar.

Definir limites do workspace

Você define os limites de taxa e os limites de gasto de um workspace em lugares diferentes:

• Limites de taxa: Em Limites de taxa no Claude Console, selecione o workspace no menu suspenso Espaço de trabalho e clique em Editar ao lado de um modelo para definir limites de solicitações por minuto, tokens de entrada ou tokens de saída.
• Limites de gasto: Na página Espaços de trabalho no Claude Console, selecione o workspace. No painel que se abre, clique em Limites de gastos para limitar o gasto mensal e configurar alertas quando o gasto atingir determinados limiares.

Arquivar um workspace

Para arquivar um workspace, abra o menu Mais ações (três pontos) do workspace e selecione Arquivar área de trabalho. O arquivamento:

• Preserva dados históricos para relatórios
• Desativa o workspace e arquiva todas as chaves de API criadas para ele
• Não pode ser desfeito

Usando a Admin API

Gerencie workspaces programaticamente usando a Admin API.

Os exemplos de SDK e CLI a seguir constroem o cliente padrão, que lê a chave da Admin API da variável de ambiente ANTHROPIC_API_KEY; o SDK expõe esses endpoints em client.organization.workspaces. Os métodos de listagem do SDK buscam páginas adicionais sob demanda, então limit define o tamanho da página; os exemplos em PHP, Ruby e curl retornam uma página.

Criar um workspace:

client = anthropic.Anthropic()

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

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

Listar workspaces:

client = anthropic.Anthropic()

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

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

Arquivar um workspace:

client = anthropic.Anthropic()

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

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

Para detalhes completos dos parâmetros e esquemas de resposta, consulte a referência da API de WorkspacesPré-visualização disponível com links para a referência da API — pressione Tab até o foco entrar no cartão, Escape para voltar..

Gerenciando membros do workspace

Adicionar um membro a um workspace:

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}")

Atualizar a função de um membro:

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}")

Remover um membro de um workspace:

client = anthropic.Anthropic()

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

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

Para detalhes completos dos parâmetros, consulte a referência da API de Membros de WorkspacePré-visualização disponível com links para a referência da API — pressione Tab até o foco entrar no cartão, Escape para voltar..

Chaves de API e escopo de recursos

Toda requisição é executada em exatamente um workspace e só pode acessar recursos dentro desse workspace. Qual workspace depende do tipo de chave:

• Uma chave de workspace (uma chave legada sem proprietário) pertence ao workspace em que foi criada e sempre é executada lá.
• Uma chave pessoal ou chave de conta de serviço atua como seu usuário ou conta de serviço. Uma chave de workspace único sempre é executada no workspace escolhido quando foi criada. Uma chave sem escopo de workspace é executada no workspace indicado pelo cabeçalho anthropic-workspace-id de cada solicitação. As contas devem ter acesso ao workspace para usá-lo.

Os recursos com escopo limitado a workspaces incluem:

• Arquivos criados por meio da Files API
• Lotes de mensagens criados por meio da Batch API
• Skills criadas por meio da Skills API

Alguns recursos são gerenciados de forma diferente:

• Túneis MCP são gerenciados com um token OAuth workspace:manage_tunnels obtido por meio de Workload Identity Federation, não uma chave de API. Os túneis são criados em um workspace, e a lista Túneis MCP do Console e o seletor de servidor do Managed Agent mostram apenas os túneis do workspace atual; o limite de 10 túneis ativos se aplica a toda a organização. O gerenciamento de túneis requer uma função com permissões de gerenciamento de túneis; os desenvolvedores da organização podem visualizá-los, mas não alterá-los.
• Workspaces em si e membros da organização são gerenciados no nível da organização por meio da Admin API, usando uma chave da Admin API, um token OAuth org:admin ou uma chave pessoal ou de conta de serviço que não tenha escopo limitado a um workspace específico.

Para consultar os IDs de workspace da sua organização, chame o endpoint Listar workspacesPré-visualização disponível com links para a referência da API — pressione Tab até o foco entrar no cartão, Escape para voltar. (passe include_default=true para incluir o workspace padrão) ou encontre-os na página Espaços de trabalho no Claude Console.

Identificar o workspace por trás de uma resposta da API

As respostas da Claude API incluem um cabeçalho anthropic-workspace-id junto com os cabeçalhos de resposta request-id e anthropic-organization-id. Seu valor é o ID com prefixo wrkspc_ do workspace para o qual a chave de API ou o token de acesso da requisição foi resolvido, inclusive quando esse workspace é o workspace padrão. Por exemplo, uma resposta bem-sucedida inclui cabeçalhos como estes:

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

O cabeçalho está ausente quando a credencial não é resolvida para um workspace (por exemplo, em requisições da Admin API) ou quando a requisição falha antes da conclusão da autenticação, como um erro 401.

Os exemplos a seguir enviam uma requisição da Messages API e leem o ID do workspace a partir dos cabeçalhos de resposta:

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

Os mesmos acessadores leem o cabeçalho de outros endpoints da Claude API também, incluindo as APIs de Claude Managed Agents. Por exemplo, leia anthropic-workspace-id da resposta que cria uma sessão para registrar a qual workspace a sessão pertence.

Com o ID do workspace de uma resposta, você pode:

• Confirmar para qual uso, custo e limites de taxa de workspace a requisição foi contabilizada
• Compará-lo com o campo workspace_id nas linhas da API de Análise de Uso e Custo, que contêm esse mesmo ID para o workspace padrão, e com o campo scope das chaves de API na Admin API, que contém o ID real do workspace ao qual uma chave está vinculada, incluindo o workspace padrão
• Verificar se é o ID do seu workspace padrão passando-o para Obter workspacePré-visualização disponível com links para a referência da API — pressione Tab até o foco entrar no cartão, Escape para voltar. com uma chave da Admin API: o workspace padrão é retornado com "name": "Default", embora Listar workspacesPré-visualização disponível com links para a referência da API — pressione Tab até o foco entrar no cartão, Escape para voltar. o omita, a menos que você passe include_default=true
• Abrir esse workspace no Console para encontrar os recursos da requisição, como sessões, arquivos, lotes de mensagens e skills

Limites de workspace

Você pode definir limites personalizados de gasto e de taxa para cada workspace para proteger contra uso excessivo e garantir a distribuição justa de recursos.

Definindo limites de workspace

Você pode definir limites de workspace menores (mas não maiores) do que os limites da sua organização:

• Limites de gasto: Limite o gasto mensal de um workspace. Para defini-los, acesse a página Espaços de trabalho (platform.claude.com/settings/workspaces) no Claude Console e selecione o workspace. No painel que se abre, clique em Limites de gastos.
• Limites de taxa: Limite solicitações por minuto, tokens de entrada por minuto ou tokens de saída por minuto. Para defini-los, acesse Limites de taxa no Claude Console, selecione o workspace no menu suspenso Espaço de trabalho e clique em Editar ao lado de um modelo.

Para obter informações detalhadas sobre “rate limits” (limites de taxa) e como eles funcionam, consulte Limites de taxa. Você também pode ler os limites de taxa atuais da sua organização e do seu workspace e definir limites de taxa do workspace programaticamente com a API de Limites de Taxa, que armazena um valor acima do limite da organização, mas ainda aplica o menor dos dois.

Rastreamento de uso e custo

Rastreie o uso e os custos por workspace usando a API de Análise de Uso e Custo:

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}")

O uso e os custos no workspace padrão são informados sob o próprio ID do workspace padrão.

Casos de uso comuns

Separação de ambientes

Crie workspaces separados para desenvolvimento, staging e produção:

Isolamento de equipe ou departamento

Atribua workspaces a diferentes equipes para alocação de custos e controle de acesso:

• Equipe de engenharia com acesso de desenvolvedor
• Equipe de ciência de dados com suas próprias chaves de API
• Equipe de suporte com acesso limitado para ferramentas de cliente

Organização baseada em projetos

Crie workspaces para projetos ou produtos específicos para rastrear uso e custos separadamente.

Melhores práticas

1. 1

   Planeje a estrutura do seu workspace

   Considere como você organizará os workspaces antes de criá-los. Pense nas necessidades de faturamento, controle de acesso e rastreamento de uso.

2. 2

   Use nomes significativos

   Nomeie os workspaces claramente para indicar sua finalidade (por exemplo, “Production - Customer Chatbot” ou “Dev - Internal Tools”).

3. 3

   Defina limites apropriados

   Configure limites de gasto e de taxa para evitar custos inesperados e garantir a distribuição justa de recursos.

4. 4

   Audite o acesso regularmente

   Revise a associação ao workspace periodicamente para garantir que apenas usuários apropriados tenham acesso.

5. 5

   Monitore o uso

   Use a API de Análise de Uso e Custo para rastrear o consumo no nível do workspace.

Perguntas frequentes

Veja também

• Admin API
• Referência da Admin API
• Limites de taxa
• API de Análise de Uso e Custo e a API de Uso e Custo legada