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 o 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 aplicativos iOS e macOS que você distribui a usuários finais.

Chaves de API

"API keys" (chaves de API) são segredos estáticos que você gera no Claude Console e envia em cada requisição no cabeçalho x-api-key.

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 deixa 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 deixa 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 única 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 que crie 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 preferíveis. Para migrar, consulte Substituindo chaves de API de workspace.

Criar e usar uma chave

• Criar uma chave: Acesse Settings → API keys no Claude Console 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 pular a definição manual de um ID de workspace em requisições futuras.
• Usar a chave: Defina o cabeçalho x-api-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
x-api-key: YOUR_API_KEY
anthropic-version: 2023-06-01
content-type: application/json

Armazene chaves de API em um gerenciador de segredos, faça a rotação delas periodicamente e desabilite ou exclua qualquer chave que você suspeite ter vazado. Na página de chaves de API, Disable é reversível (a Admin API reporta o status da chave como "inactive", e Re-enable a 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 funcionam apenas 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 nos SDKs.

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

Você pode encontrar o ID de um workspace na coluna ID de Settings → Workspaces no Claude Console, ou chamando o endpoint List Workspaces. Nenhum dos dois lista o ID do Default Workspace: leia-o no cabeçalho de resposta anthropic-workspace-id de qualquer requisição executada nele (por exemplo, uma feita com uma chave de workspace do Default Workspace), ou em scope.workspace_id de tal chave em List API Keys.

client = Anthropic()  # reads ANTHROPIC_API_KEY

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

# Ou defina uma vez para todas as requisições 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 se o usuário ou a 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 dada para qualquer workspace desconhecido.

O Workload Identity Federation, por sua vez, seleciona um workspace na troca de token; 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: uma predefinição (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 por conta própria. Se sua organização tiver uma política de expiração máxima, o Console limita as predefinições 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 de 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 vida útil de pelo menos 14 dias, e 1 dia antes para chaves com vida útil de pelo menos 7 dias. Chaves com vida útil mais curta expiram sem 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 reporta o timestamp expires_at de cada chave nos endpoints List API Keys e Retrieve API Key, para que você possa auditar e rotacionar chaves antes que expirem. O campo é null para chaves sem expiração.

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

Substituindo chaves de API de workspace

Se você tem uma chave de workspace, pode querer substituí-la por Workload Identity Federation ou por 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 o Workload Identity Federation, que é preferível a 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. Suas próprias ferramentas devem 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 em Settings → Service accounts 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, normalmente a variável de ambiente ANTHROPIC_API_KEY ou uma entrada no 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.

Workload Identity Federation

O "Workload Identity Federation" (federação de identidade de carga de trabalho), ou WIF, permite que uma carga de trabalho se autentique com um token de identidade de curta duração emitido por um "identity provider" (provedor de identidade), ou 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 da Claude API de curta duração, e o SDK renova esse token automaticamente antes que ele expire. Não há nenhuma string sk-ant-api... para emitir, distribuir ou rotacionar.

A federação remove chaves de longa duração da Claude API 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 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 capaz de emitir tokens do IdP) ainda pode comprometê-la. Combine a federação com os controles do seu provedor, como listas de permissão de IP, MFA e logs 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

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

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

Próximos passos