Workspaces

Os "workspaces" (espaços de trabalho) oferecem uma forma de organizar o uso da 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 Default Workspace (workspace padrão) que não pode ser renomeado, arquivado nem excluído. Ao criar workspaces adicionais, você pode atribuir membros, contas de serviço, chaves de API e limites de recursos a cada um deles.

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 a equipe da sua conta se precisar de mais
• O Default Workspace tem um ID wrkspc_ como qualquer outro workspace (retornado no cabeçalho de resposta anthropic-workspace-id e aceito por Get Workspace), mas não aparece nos resultados de List Workspaces, e chaves de API, relatórios de uso e relatórios de custo mostram null para seu workspace_id, assim como as chaves de API de todos os workspaces (o campo scope de uma chave de API as diferencia; para uma chave vinculada ao Default Workspace, ele traz o ID real)
• Chaves de API podem ter escopo restrito a um único workspace. Nesse caso, elas só podem acessar recursos dentro desse workspace. Algumas chaves de API podem receber permissões em vários workspaces e fornecem um cabeçalho de ID de workspace para acessar recursos dentro desse 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. Cada membro subsequente que fizer 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 emite uma chave de API por usuário nesse 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, diferentemente 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 Settings > Workspaces.
• É o único workspace que oferece suporte a limites de gastos mensais por usuário.

Funções e permissões de workspace

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

Herança de funções

• Administradores da organização recebem automaticamente acesso de Workspace Admin a todos os workspaces
• Membros de faturamento da organização recebem automaticamente acesso de Workspace Billing 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 aos workspaces a partir da página da conta de serviço em Settings → Service accounts ou a partir da aba Service accounts do workspace

Gerenciando workspaces

Usando o Console

Crie e gerencie workspaces no Claude Console.

Criar um workspace

1. 1

   Abra as configurações de workspace

   No Claude Console, acesse Settings > Workspaces.

2. 2

   Crie um workspace

   Clique em Create workspace.

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 Create para finalizar.

Editar detalhes do workspace

Para modificar o nome ou a cor de um workspace:

1. Selecione o workspace na lista.
2. Clique no menu de reticências (...) e escolha Edit details.
3. Atualize o nome ou a cor e salve suas alterações.

Adicionar membros a um workspace

1. Navegue até a aba Members do workspace.
2. Clique em Add to Workspace.
3. Selecione um membro da organização e atribua a ele uma função de workspace.
4. Confirme a adição.

Para remover um membro, clique no ícone de lixeira ao lado do nome dele.

Definir limites do workspace

As configurações de cada workspace dividem esses limites em duas abas:

• Limites de taxa: Na aba Rate limits, defina limites por nível de modelo para requisições por minuto, tokens de entrada ou tokens de saída
• Limites de gastos: Na aba Spend limits, limite os gastos mensais e configure alertas para quando os gastos atingirem determinados patamares

Arquivar um workspace

Para arquivar um workspace, clique no menu de reticências (...) e selecione Archive. O arquivamento:

• Preserva os 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 de Admin API da variável de ambiente ANTHROPIC_API_KEY; os SDKs expõem esses endpoints em client.beta.organization.workspaces. Os métodos de listagem dos SDKs buscam páginas adicionais sob demanda, portanto 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.beta.organization.workspaces.create(name="Production")

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

Listar workspaces:

client = anthropic.Anthropic()

workspaces = client.beta.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.beta.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 Workspaces.

Gerenciando membros do workspace

Adicionar um membro a um workspace:

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

Atualizar a função de um membro:

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

Remover um membro de um workspace:

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

Para detalhes completos dos parâmetros, consulte a referência da API de Membros do Workspace.

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 nele.
• 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 ela foi criada. Uma chave de múltiplos workspaces é executada no workspace indicado pelo cabeçalho anthropic-workspace-id de cada requisição. As contas precisam ter acesso ao workspace para usá-lo.

Os recursos com escopo de workspace 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 com uma chave de API. Os túneis são criados em um workspace, e a lista MCP tunnels 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 exige uma função com permissões de gerenciamento de túneis; desenvolvedores da organização podem visualizá-los, mas não alterá-los.
• Os próprios workspaces e os membros da organização são gerenciados no nível da organização por meio da Admin API, usando uma chave de Admin API, um token OAuth org:admin ou uma chave pessoal ou de conta de serviço que não tenha escopo restrito a um workspace específico.

Para consultar os IDs de workspace da sua organização, chame o endpoint List Workspaces ou encontre-os 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 Default Workspace. 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 de a autenticação ser concluída, como em um erro 401.

Os exemplos a seguir enviam uma requisição à Messages API e imprimem 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",
    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 do 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 o uso, o custo e os limites de taxa de qual workspace a requisição foi contabilizada
• Compará-lo com o campo workspace_id nos relatórios da Usage and Cost API e em objetos da Admin API, como chaves de API (ambos informam null para o Default Workspace, assim como as chaves de API também fazem para chaves de todos os workspaces; o campo scope de uma chave de API diferencia os dois casos e, para uma chave vinculada a um único workspace, traz o ID real desse workspace)
• Verificar se é o ID do seu Default Workspace passando-o para Get Workspace com uma chave de Admin API: o Default Workspace retorna com "name": "Default", embora List Workspaces o omita
• 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 gastos e de taxa para cada workspace para se proteger contra uso excessivo e garantir uma distribuição justa de recursos.

Definindo limites de workspace

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

• Limites de gastos: Limite os gastos mensais de um workspace. Defina-os na aba de configurações Spend limits do workspace no Claude Console.
• Limites de taxa: Limite requisições por minuto, tokens de entrada por minuto ou tokens de saída por minuto. Defina-os na aba de configurações Rate limits do workspace no Claude Console.

Para informações detalhadas sobre limites de taxa e como eles funcionam, consulte Limites de taxa. Você também pode ler programaticamente os limites de taxa atuais da sua organização e dos seus workspaces com a Rate Limits API.

Rastreamento de uso e custos

Rastreie o uso e os custos por workspace usando a 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"

O uso e os custos atribuídos ao Default Workspace têm valor null para workspace_id.

Casos de uso comuns

Separação de ambientes

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

Isolamento por 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 atendimento ao cliente

Organização por projeto

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

Melhores práticas

1. 1

   Planeje a estrutura dos seus workspaces

   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 de forma clara para indicar sua finalidade (por exemplo, "Production - Customer Chatbot" ou "Dev - Internal Tools").

3. 3

   Defina limites apropriados

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

4. 4

   Audite o acesso regularmente

   Revise periodicamente os membros dos workspaces para garantir que apenas os usuários apropriados tenham acesso.

5. 5

   Monitore o uso

   Use a Usage and Cost API para rastrear o consumo no nível de workspace.

Perguntas frequentes

Veja também

• Admin API
• Referência da Admin API
• Limites de taxa
• Usage and Cost API