Autenticando Chamadas da API Claude com o Cabeçalho x-api-key

Toda solicitação para a API Claude precisa provar quem está chamando antes que o servidor faça qualquer outra coisa.

Essa prova é um único cabeçalho: x-api-key, carregando sua chave de API.

Esta página cobre onde obter uma chave, como configurá-la para o SDK Python e como enviá-la manualmente quando você não estiver usando o SDK.

Resumo

O cabeçalho x-api-key é como a API Claude autentica cada solicitação, verificado antes mesmo que o corpo da solicitação seja inspecionado.

O SDK oficial Python lê sua chave da variável de ambiente ANTHROPIC_API_KEY por padrão, então a maioria do código nunca toca o cabeçalho diretamente.

Você também pode passar a chave explicitamente para o construtor do cliente, o que é útil para configurações de várias chaves ou rotação de chaves por solicitação.

Chamadores HTTP brutos (curl, requests, ou o cliente HTTP de outra linguagem) devem definir x-api-key por conta própria, juntamente com alguns outros cabeçalhos obrigatórios.

Tratar chaves de API como qualquer outro segredo, nunca codificado, nunca commitado, rotacionado em um cronograma, é a diferença entre um susto menor e um incidente real.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

import os
import anthropic
 
# Opção 1: implícita - o SDK lê ANTHROPIC_API_KEY do ambiente
client = anthropic.Anthropic()
 
# Opção 2: explícita - passe a chave diretamente
client = anthropic.Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])

Quando usar isso:

• Configurando um novo projeto: use a abordagem de variável de ambiente (Opção 1).
• Suportando várias contas ou rotação de chaves em um único processo: use o argumento explícito api_key (Opção 2).
• Chamando a API sem o SDK: defina o cabeçalho x-api-key manualmente (veja Exemplo de Funcionamento).
• Executando em CI ou em um contêiner: injete ANTHROPIC_API_KEY através do mecanismo de segredos da sua plataforma, não de um arquivo commitado.

Exemplo de Funcionamento

import os
import anthropic
 
def get_client() -> anthropic.Anthropic:
    api_key = os.environ.get("ANTHROPIC_API_KEY")
    if not api_key:
        raise RuntimeError(
            "ANTHROPIC_API_KEY não está definida. Exporte-a antes de executar este script."
        )
    return anthropic.Anthropic(api_key=api_key)
 
 
def main() -> None:
    client = get_client()
    response = client.messages.create(
        model="claude-sonnet-5-20260630",
        max_tokens=100,
        messages=[{"role": "user", "content": "Confirme que a autenticação está funcionando."}],
    )
    print(response.content[0].text)
 
 
if __name__ == "__main__":
    main()

O que isso demonstra:

• Falha rápida com uma mensagem de erro clara quando a chave está faltando, em vez de deixar um 401 críptico aparecer mais tarde.
• Leitura explícita da chave do ambiente, o que torna a dependência visível no topo do script.
• Passagem explícita de api_key para o construtor, que funciona de forma idêntica a deixar o SDK ler a variável de ambiente por si só.

Mergulho Profundo

Como Funciona

• O construtor anthropic.Anthropic() do SDK verifica primeiro um argumento explícito api_key; se nenhum for fornecido, ele volta a ler ANTHROPIC_API_KEY do ambiente do processo.
• Internamente, o SDK anexa sua chave como o cabeçalho x-api-key em cada solicitação HTTPS de saída, você nunca precisa defini-la por chamada.
• O servidor valida este cabeçalho antes de analisar o restante do corpo da solicitação, é por isso que as falhas de autenticação retornam rapidamente e independentemente de seu prompt ou parâmetros serem válidos.
• Uma chave ausente ou inválida gera anthropic.AuthenticationError em Python, mapeada de uma resposta HTTP 401.

HTTP Bruto Sem o SDK

Se você estiver chamando a API diretamente (para uma linguagem sem SDK, ou para depurar no nível HTTP), defina o cabeçalho você mesmo:

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2026-01-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-5-20260630",
    "max_tokens": 100,
    "messages": [{"role": "user", "content": "Olá"}]
  }'

Note que chamadas brutas precisam de ambos os cabeçalhos x-api-key e anthropic-version; o SDK define o cabeçalho de versão para você automaticamente.

Opções de Armazenamento de Chave

Notas Python

# Prefira os.environ[...] (gera KeyError ruidosamente) em vez de os.environ.get(...)
# com um fallback silencioso de None, quando a chave é genuinamente necessária:
import os
 
api_key = os.environ["ANTHROPIC_API_KEY"]  # gera um erro claramente se ausente

Armadilhas

• Codificar a chave diretamente no código fonte. Ela acaba no histórico do controle de versão permanentemente, mesmo que você a exclua em um commit posterior. Correção: use variáveis de ambiente ou um gerenciador de segredos e adicione .env ao .gitignore antes do primeiro commit que o tocar.
• Comitar um arquivo .env por acidente. Uma entrada .gitignore ausente ou mal configurada vaza silenciosamente a chave. Correção: adicione .env ao .gitignore primeiro e, em seguida, verifique com git status que ele não está sendo rastreado antes do seu primeiro commit.
• Confundir 401 (chave errada) com 403 (chave válida, sem permissão). Ambos são erros de estágio de autenticação, mas precisam de correções diferentes. Correção: verifique o código de status da exceção; 401 significa regenerar ou corrigir a chave, 403 significa verificar as permissões/escopo da chave em sua conta.
• Registrar o objeto de solicitação completo, incluindo cabeçalhos, na saída de depuração. Isso pode vazar a chave para arquivos de log ou ferramentas de observabilidade. Correção: limpe ou omita o cabeçalho x-api-key ao registrar solicitações.
• Compartilhar uma chave em todos os ambientes (dev, staging, prod). Um vazamento ou bug em um ambiente compromete todos eles. Correção: emita chaves separadas por ambiente para que você possa revogar uma sem afetar as outras.
• Esquecer o cabeçalho anthropic-version em chamadas HTTP brutas. Chamadores brutos às vezes copiam o cabeçalho de autenticação, mas esquecem este, causando falhas confusas não relacionadas à autenticação em si. Correção: sempre envie ambos os cabeçalhos juntos para chamadas não SDK.

Alternativas

FAQs

Relacionados

• Entendendo o Ciclo de Vida da Solicitação da API Claude - onde a autenticação se encaixa no fluxo geral da solicitação.
• Instalando e Configurando o SDK Python da Anthropic - configuração do cliente além da chave.
• Referência de Códigos de Erro e Solução de Problemas da API Claude - lista completa de códigos de erro relacionados à autenticação.
• Construindo um Wrapper Reutilizável para o Cliente da API Claude - centralizando o manuseio de chaves em um aplicativo.

Versões da Pilha: Escrito contra a linha de modelos Claude atual em ~junho de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (o padrão) e Claude Haiku 4.5 - e o SDK oficial anthropic para Python (última versão 0.x). Nomes de modelos, versões de SDK e preços mudam rapidamente - verifique os detalhes atuais em platform.claude.com/docs antes de confiar neles.