Autenticação

A Claude API oferece suporte a três formas de autenticar requisições:

Chaves de API e Workload Identity Federation concedem o mesmo acesso aos endpoints da Claude API. Escolha chaves de API para começar rapidamente: uma chave pessoal para seu próprio desenvolvimento, ou uma chave de conta de serviço para qualquer coisa compartilhada. Migre para Workload Identity Federation quando sua carga de trabalho já tiver uma identidade emitida pela plataforma que você possa federar. Use App Attest para apps iOS e macOS que você distribui a usuários finais.

Chaves de API

Chaves de API são segredos estáticos que você gera no Claude Console e envia em cada requisição como um bearer token no cabeçalho Authorization.

Tipos de chave

Ao criar uma chave, você escolhe seu tipo, que determina o que a chave pode fazer, onde ela funciona e quando ela para de funcionar:

Chaves pessoais e chaves de conta de serviço são respaldadas por identidade: cada uma pertence a um usuário ou conta de serviço que sua organização já gerencia, e cada requisição atua como essa identidade. Quando essa identidade é removida da organização, a chave para de funcionar. Isso significa que as chaves não sobreviverão acidentalmente às pessoas ou cargas de trabalho que as possuem. Prefira-as em vez de chaves de workspace para novas integrações.

Use uma chave pessoal para seu próprio desenvolvimento e scripts. Uma chave pessoal compartilhada atua como uma pessoa e quebra quando ela sai. Para cargas de trabalho compartilhadas ou automatizadas (CI, serviços de produção), peça a um administrador da organização para criar uma conta de serviço para que a carga de trabalho tenha sua própria identidade.

Chaves de API de workspace ainda funcionam, mas devem ser consideradas legado; chaves respaldadas por identidade ou Workload Identity Federation são preferidas. Para migrar, consulte Substituindo chaves de API de workspace.

Criar e usar uma chave

• Criar uma chave: No Claude Console, acesse a página API keys (platform.claude.com/settings/keys) e clique em Create key. Dê um nome à chave e escolha uma expiração. Defina Linked account como você mesmo para uma chave pessoal, ou como uma conta de serviço para uma chave compartilhada entre vários usuários. Você também pode restringir a chave a um workspace específico, o que permite dispensar a definição manual de um ID de workspace em requisições futuras.
• Usar a chave: Envie-a como Authorization: Bearer <key> em requisições HTTP diretas, ou defina a variável de ambiente ANTHROPIC_API_KEY e os SDKs de cliente a detectam automaticamente.

POST /v1/messages
Authorization: Bearer YOUR_API_KEY
anthropic-version: 2023-06-01
content-type: application/json

O cabeçalho legado x-api-key: YOUR_API_KEY ainda é suportado no lugar de Authorization.

Armazene chaves de API em um gerenciador de segredos, faça a rotação delas periodicamente e desative ou exclua qualquer chave que você suspeite ter vazado. Na página de chaves de API no Claude Console, Disable é reversível (a Admin API informa o status da chave como "inactive", e Re-enable o retorna para "active"), enquanto Delete é permanente: a chave é arquivada e ainda aparece em List API Keys com status: "archived". Chaves expiradas só podem ser excluídas. Você também pode definir uma expiração ao criar uma chave para limitar por quanto tempo uma credencial vazada permanece utilizável.

client = Anthropic(api_key="my-anthropic-api-key")
# ou, com ANTHROPIC_API_KEY definida no ambiente:
client = Anthropic()

Selecionar um workspace

Chaves de API criadas para um workspace específico só funcionam nesse workspace, e requisições de API que usam essas chaves podem omitir o ID do workspace.

Se sua chave de API não estiver restrita a um workspace, você deve especificar o ID do workspace no cabeçalho anthropic-workspace-id em cada requisição. Veja o exemplo a seguir para saber como definir esse cabeçalho em uma requisição ou em SDKs.

A Admin API aceita uma chave pessoal ou chave de conta de serviço apenas se a chave não estiver restrita a um workspace específico.

Você pode encontrar o ID de um workspace na coluna ID da página Workspaces (platform.claude.com/settings/workspaces) no Claude Console, ou chamando o endpoint List Workspaces. List Workspaces inclui o Default Workspace somente quando você passa include_default=true; o ID dele também aparece no cabeçalho de resposta anthropic-workspace-id de qualquer requisição executada nele.

client = Anthropic()  # reads ANTHROPIC_API_KEY

# Obrigatório em toda requisição para uma chave multi-workspace.
# Omita extra_headers para uma chave de workspace único.
message = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
    extra_headers={"anthropic-workspace-id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ"},
)
print(message.content)

# Ou defina-o uma vez para toda requisição deste cliente:
workspace_client = Anthropic(
    default_headers={"anthropic-workspace-id": "wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ"},
)

Se uma requisição feita com uma chave que não está restrita a um workspace omitir o cabeçalho, a API retorna um 400 invalid_request_error:

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "anthropic-workspace-id is required when authenticating with an identity-linked API key; send the id of the workspace this request acts in."
  },
  "request_id": "req_011CSHoEeqs5C35K2UUqR7Fy"
}

Um valor de cabeçalho que não seja um ID de workspace válido retorna um 400 invalid_request_error com a mensagem anthropic-workspace-id header must be a valid workspace ID. Se o workspace não existir, ou o usuário ou conta de serviço da chave não tiver acesso a ele, a API retorna um 404 not_found_error com a mensagem Workspace `<id>` not found., a mesma resposta que para qualquer workspace desconhecido.

Workload Identity Federation seleciona um workspace na troca de token em vez disso; consulte a referência do WIF para detalhes.

Expiração de chave

Ao criar uma chave de API na página de chaves de API no Claude Console, você escolhe uma expiração: um valor predefinido (3 horas, 1 dia, 7 dias ou 30 dias), uma duração personalizada, ou Never para chaves que você armazena em um gerenciador de segredos e rotaciona você mesmo. Se sua organização tiver uma política de expiração máxima, o Console limita os valores predefinidos e durações personalizadas ao máximo da política, e Never fica indisponível. Chaves existentes mantêm seu comportamento atual; a expiração é definida no momento da criação e não pode ser alterada depois. A mesma escolha de expiração se aplica quando você cria uma chave da Admin API no Claude Console.

A Anthropic envia um e-mail ao criador da chave conforme a expiração se aproxima: 7 dias antes da expiração para chaves criadas com um tempo de vida de pelo menos 14 dias, e 1 dia antes para chaves com um tempo de vida de pelo menos 7 dias. Chaves com tempos de vida mais curtos expiram sem um e-mail de aviso.

Depois que uma chave expira, requisições feitas com ela retornam um 401 authentication_error. Crie uma nova chave para restaurar o acesso; chaves expiradas não podem ser reativadas.

A tabela de chaves de API do Console mostra a expiração de cada chave, e a Admin API informa o timestamp expires_at de cada chave nos endpoints List API Keys e Retrieve API Key, para que você possa auditar e fazer a rotação das chaves antes que expirem. O campo é null para chaves sem expiração.

A expiração limita o tempo de vida de uma credencial vazada, mas não substitui a higiene de segredos. Independentemente da expiração, armazene chaves em um gerenciador de segredos e desative ou exclua qualquer chave que você suspeite ter vazado.

Substituindo chaves de API de workspace

Se você tiver uma chave de workspace, pode querer substituí-la por Workload Identity Federation ou uma chave pessoal ou de conta de serviço. Isso proporciona melhor segurança e observabilidade.

Consulte Workload Identity Federation para detalhes sobre como configurar Workload Identity Federation, que é preferido em vez de chaves de longa duração.

Para substituir uma chave de workspace por uma chave pessoal ou de conta de serviço:

1. Decida o tipo de chave. Seu próprio ferramental deve usar uma chave pessoal. Uma carga de trabalho compartilhada ou não supervisionada deve usar uma chave de conta de serviço.
2. Crie uma conta de serviço, se necessário. Talvez você precise pedir a um administrador da organização que crie uma na página Service accounts (platform.claude.com/settings/service-accounts) no Claude Console e a adicione ao workspace relevante.
3. Crie a nova chave. Crie-a especificamente para o workspace da integração, a menos que vários workspaces sejam necessários.
4. Implante a nova chave. Substitua a chave antiga onde quer que a integração a leia, tipicamente a variável de ambiente ANTHROPIC_API_KEY ou uma entrada de gerenciador de segredos. Para uma chave de múltiplos workspaces, envie também o cabeçalho anthropic-workspace-id conforme mostrado em Selecionar um workspace.
5. Exclua a chave antiga. Confirme que as requisições são bem-sucedidas e, em seguida, exclua a chave de workspace na página de chaves de API no Claude Console.

Workload Identity Federation

Workload Identity Federation (WIF) permite que uma carga de trabalho se autentique com um token de identidade de curta duração emitido por um provedor de identidade (IdP) em que você já confia, como AWS IAM, Google Cloud, ou qualquer emissor OIDC compatível com os padrões (como GitHub Actions, contas de serviço do Kubernetes, SPIFFE, Microsoft Entra ID ou Okta). A carga de trabalho troca seu JWT emitido pelo IdP em POST /v1/oauth/token por um token de acesso de curta duração da Claude API, e o SDK atualiza esse token automaticamente antes que ele expire. Não há nenhuma string sk-ant-api... para gerar, distribuir ou rotacionar.

A federação remove chaves de API da Claude de longa duração do seu ambiente, o que reduz o raio de impacto de uma credencial vazada e permite que você gerencie o acesso com os mesmos controles de IdP que você já usa para recursos de nuvem. Ela não garante, por si só, segurança de ponta a ponta: a cadeia de confiança é tão forte quanto a configuração do seu provedor de identidade, e um segredo de longa duração um salto acima (por exemplo, uma credencial de nuvem estática que pode gerar tokens de IdP) ainda pode comprometê-la. Combine a federação com os controles do seu provedor, como listas de permissão de IP, MFA e registro de auditoria.

Para configurar a federação, você cria três recursos no Claude Console (uma conta de serviço, um emissor de federação e uma regra de federação) e então aponta seu SDK para a regra. Consulte Workload Identity Federation para o passo a passo completo de configuração.

App Attest

App Attest autentica apps iOS e macOS que chamam a Claude API diretamente do dispositivo. Cada instalação prova que é um build genuíno e não modificado de um app que você registrou no Claude Console, usando o serviço App Attest da Apple. A Anthropic então emite ao dispositivo um token de acesso de curta duração que cobra o uso ao seu workspace. Os tokens são restritos ao seu workspace, expiram após uma hora e autorizam apenas chamadas à Messages API.

Para registrar seu app e obter um client ID, consulte App Attest para apps iOS e macOS.

Próximos passos