Como autenticar a Claude API: chave, Bedrock ou Vertex

As quatro formas de autenticação da Claude API

A autenticação da Claude API resume-se a uma decisão: qual credencial o cliente envia pela rede. Existem quatro opções, e não são variantes do mesmo mecanismo. A API Anthropic direta envia uma chave estática num cabeçalho x-api-key. O Amazon Bedrock assina cada pedido com credenciais AWS, e não existe nenhuma chave Anthropic nessa configuração. O Google Cloud envia um token de acesso Google de curta duração. O Microsoft Foundry aceita uma chave emitida pelo Azure ou um token Microsoft Entra.

Este guia destina-se à integração de um SDK (kit de desenvolvimento de software) num serviço em execução num servidor Linux. Se estiver a configurar a ferramenta de linha de comandos Claude Code, as variáveis e o fluxo são diferentes: consulte configurar o Claude Code para usar o Bedrock ou o Vertex. Se o serviço ainda não existir, crie-o primeiro com criar a primeira aplicação Claude API numa VPS e volte aqui para configurar a credencial.

Tudo o que se segue foi verificado com base na documentação da plataforma Anthropic em agosto de 2026. Os identificadores de modelos, os preços, as versões dos SDK e os formatos dos endpoints mudam com frequência. Por isso, este guia inclui ligações para as páginas dos fornecedores em vez de apresentar valores que ficam desatualizados.

Rota 1: uma chave de API da Anthropic

Este é o caminho direto e o único em que a Anthropic emite o segredo. Os pedidos são enviados para o endpoint Messages no host da API da Anthropic, e cada pedido inclui três cabeçalhos.

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model": "MODEL_ID", "max_tokens": 64, "messages": [{"role": "user", "content": "Hello"}]}'

Substitua MODEL_ID por um identificador atual da visão geral dos modelos da Anthropic. Uma resposta correta é um JSON que contém um array content e um objeto usage. Uma chave incorreta ou expirada devolve HTTP 401 com authentication_error. A ausência do cabeçalho anthropic-version é uma falha diferente, porque esse cabeçalho é obrigatório em todos os pedidos; os SDKs configuram-no automaticamente.

A criação do cliente é a mais simples das quatro, porque não há nada para construir. Todos os SDKs oficiais leem ANTHROPIC_API_KEY do ambiente automaticamente.

import os
from anthropic import Anthropic

client = Anthropic()  # reads ANTHROPIC_API_KEY from the environment

message = client.messages.create(
    model=os.environ["CLAUDE_MODEL"],
    max_tokens=64,
    messages=[{"role": "user", "content": "Hello"}],
)
print(message.usage)

Vale a pena manter o identificador do modelo no ambiente, junto da chave. Os nomes dos modelos mudam segundo um calendário que não controla, e voltar a implementar o código para editar uma única string é trabalho evitável.

As chaves são criadas na Console, onde escolhe a validade no momento da criação: predefinições de 3 horas, 1 dia, 7 dias ou 30 dias, uma duração personalizada ou Never. A validade é definida na criação e não pode ser alterada posteriormente. A Anthropic envia um email ao criador da chave antes de uma chave de longa duração expirar, mas uma chave com validade curta expira sem qualquer email de aviso. Uma chave expirada devolve 401 e não pode ser reativada, pelo que a correção é sempre criar uma chave nova.

Não há nenhuma região para escolher na API direta, e a faturação é feita diretamente à sua organização Anthropic. Os workspaces limitam uma chave a um único projeto, que é a forma mais simples de saber quanto um serviço individual gasta. Para a matemática por trás dessa faturação, consulte como os preços da API por token se comparam com uma subscrição.

Há ainda uma opção que pertence a esta secção, porque elimina totalmente o segredo estático. A Workload Identity Federation permite que uma carga de trabalho troque um token OpenID Connect (OIDC) de um fornecedor de identidade em que já confia por um token Anthropic de curta duração em POST /v1/oauth/token, e o SDK renova esse token antes de expirar. Nunca é criada nem copiada qualquer string sk-ant-api.... Esta opção adapta-se a Kubernetes, GitHub Actions e VMs na cloud, que já têm uma identidade da plataforma. Um VPS comum normalmente não tem um emissor desse tipo, pelo que, nesse servidor, uma chave de API num ficheiro é a resposta correta, e o resto deste guia pressupõe essa configuração.

Rota 2: credenciais da AWS no Amazon Bedrock

No Bedrock, não tem qualquer chave da Anthropic. O SDK assina cada pedido HTTP com o AWS Signature Version 4 (SigV4), usando credenciais AWS normais, e a AWS decide se essa identidade pode invocar o modelo.

pip install -U "anthropic[bedrock]"
aws sts get-caller-identity

aws sts get-caller-identity mostra o número da conta e o ARN (Amazon Resource Name) da identidade que as suas credenciais resolvem. Execute-o antes de qualquer outra ação. Se falhar, a chamada ao Claude também falhará, porque o SDK percorre a mesma cadeia: primeiro os argumentos do construtor, depois as variáveis de ambiente AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN e AWS_REGION, depois o ficheiro de configuração da AWS e o restante da cadeia padrão (SSO, funções assumidas, a função da tarefa ECS e o serviço de metadados da instância).

Na construção do cliente, só mudam a classe e um argumento.

from anthropic import AnthropicBedrock

client = AnthropicBedrock(aws_region="us-east-1")

Aqui, a região não é apenas um detalhe. Os endpoints do Bedrock são específicos de cada região, o acesso aos modelos é concedido por região na consola da AWS e a região faz parte da assinatura SigV4. Por isso, uma assinatura calculada para uma região é rejeitada por outra. Defina AWS_REGION explicitamente no ambiente do serviço. A Anthropic documenta que o cliente AnthropicBedrock lê AWS_REGION e recorre a us-east-1 quando essa variável não está definida. Também documenta que não lê ~/.aws/config para determinar a região. É por isso que a AWS CLI pode listar os modelos Claude com sucesso na mesma máquina onde o processo Python falha: a CLI leu o ficheiro de configuração e o cliente não.

Numa instância EC2, associe uma função IAM (identity and access management). Nenhum segredo é gravado no disco, porque o serviço de metadados da instância fornece credenciais temporárias ao SDK. Um VPS fora da AWS não tem uma função de instância nem um serviço de metadados. Nesse caso, pode escolher entre manter na máquina o par de chaves de acesso de longa duração de um utilizador IAM, que pertence à mesma categoria de segredo que uma chave da Anthropic, e usar federação: autenticar-se no seu fornecedor de identidade, chamar o AWS STS (security token service) e usar as credenciais temporárias devolvidas. O Bedrock também aceita um token bearer através de AWS_BEARER_TOKEN_BEDROCK, documentado com um limite de 12 horas e descrito pela AWS como a opção menos preferida.

A cobrança é feita na sua conta AWS, e não junto da Anthropic. Normalmente, esse é precisamente o motivo para escolher esta opção. Os endpoints regionais têm um acréscimo de 10% em relação ao endpoint global, conforme documentado em agosto de 2026. Há um erro do Bedrock que convém reconhecer porque parece um problema de permissões, mas não é: Invocation of model ID ... with on-demand throughput isn't supported. Retry your request with the ID or ARN of an inference profile that contains this model. Isso é encaminhamento do modelo. Alterar as credenciais não resolverá o problema.

Rota 3: credenciais do Google no Vertex AI

O Google Cloud usa Application Default Credentials (ADC), uma ordem de pesquisa fixa que as bibliotecas de autenticação do Google seguem para encontrar uma credencial sem que seja necessário indicar uma. O ADC verifica primeiro GOOGLE_APPLICATION_CREDENTIALS, depois o ficheiro criado por gcloud auth application-default login e, por fim, a conta de serviço associada através do servidor de metadados.

pip install -U "anthropic[vertex]"
gcloud auth application-default login

Numa estação de trabalho, esse início de sessão cria $HOME/.config/gcloud/application_default_credentials.json e o processo termina aí. Num servidor, é a ferramenta errada, porque a credencial armazenada pertence a uma pessoa e deixa de funcionar quando a conta dessa pessoa é removida. Fora do Google Cloud, também não existe um servidor de metadados. Por isso, o ADC recorre a GOOGLE_APPLICATION_CREDENTIALS, que aponta para um ficheiro de chave de uma conta de serviço. Esse ficheiro JSON é um segredo de longa duração e requer exatamente o tratamento descrito mais adiante neste guia. Dentro do Google Cloud, associe uma conta de serviço à VM. Assim, não existe nenhum ficheiro para proteger.

from anthropic import AnthropicVertex

client = AnthropicVertex(project_id="my-project", region="global")

Duas coisas mudam quando se desce do SDK para HTTP direto. O identificador do modelo sai do corpo do pedido e passa para o caminho do URL. anthropic_version sai do cabeçalho e passa para o corpo, onde tem de usar vertex-2023-10-16. A credencial é um token de acesso comum do Google.

curl https://aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/global/publishers/anthropic/models/${MODEL_ID}:rawPredict \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{"anthropic_version": "vertex-2023-10-16", "max_tokens": 64, "messages": [{"role": "user", "content": "Hello"}]}'

A região é um argumento de primeira classe. global faz o encaminhamento dinâmico para garantir disponibilidade. us e eu são identificadores multirregionais. Um nome como us-east5 fixa uma única região. Os endpoints multirregionais e regionais custam mais 10% do que o endpoint global, conforme documentado em agosto de 2026. A faturação é feita através do projeto Google Cloud. Por isso, as quotas e as faturas são da Google.

Rota 4: Microsoft Foundry é a rota do Azure

Se procurou Claude no Azure, esta é a secção pretendida, e existe uma rota suportada. Claude é executado no Microsoft Foundry (anteriormente Azure AI Foundry), com faturação através do Azure Marketplace em Claude Consumption Units. Crie um recurso do Foundry, implemente um modelo Claude nesse recurso e faça chamadas para um endpoint alojado no Azure em https://{resource}.services.ai.azure.com/anthropic/v1/*.

Há duas credenciais disponíveis. A primeira é uma chave emitida pelo Azure, disponível no separador Details da implementação no portal do Foundry, enviada num cabeçalho api-key ou x-api-key. A segunda é um token do Microsoft Entra. É a melhor opção num servidor porque o controlo de acesso baseado em funções do Azure determina quem pode chamar o endpoint.

ACCESS_TOKEN=$(az account get-access-token --resource https://ai.azure.com --query accessToken -o tsv)

curl https://${RESOURCE}.services.ai.azure.com/anthropic/v1/messages \
  -H "content-type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -d '{"model": "DEPLOYMENT_NAME", "max_tokens": 64, "messages": [{"role": "user", "content": "Hello"}]}'

O campo model contém o nome da implementação, não um identificador de modelo. Por predefinição, os dois valores são iguais. Deixam de ser iguais assim que atribui um nome personalizado à implementação. Essa é a causa habitual de um erro Deployment not found numa chamada que, de resto, está correta. Os SDKs de Python e TypeScript leem ANTHROPIC_FOUNDRY_API_KEY e ANTHROPIC_FOUNDRY_RESOURCE do ambiente. O suporte do Foundry não está disponível em todos os SDKs. Conforme documentado em agosto de 2026, abrange C#, Java, PHP, Python e TypeScript. Os SDKs de Go e Ruby precisam do cliente genérico apontado para o URL base do Foundry.

Essa solução alternativa tem um risco específico. Se ANTHROPIC_API_KEY continuar definido no ambiente, o cliente genérico utiliza-o e envia a sua chave Anthropic para um endpoint da Microsoft. Remova a variável do ambiente ou desative os valores predefinidos do ambiente no cliente. Os tokens do Entra expiram ao fim de cerca de uma hora. Por isso, um processo de execução prolongada tem de os renovar, em vez de guardar um token no arranque.

Quanto tempo dura a credencial no seu servidor?

[
  {
    "label": "Anthropic key, 30-day preset",
    "max_lifetime_hours": 720
  },
  {
    "label": "Anthropic key, 7-day preset",
    "max_lifetime_hours": 168
  },
  {
    "label": "AWS STS assumed role",
    "max_lifetime_hours": 12
  },
  {
    "label": "Bedrock bearer token",
    "max_lifetime_hours": 12
  },
  {
    "label": "Entra ID access token",
    "max_lifetime_hours": 1
  },
  {
    "label": "Federated Anthropic token",
    "max_lifetime_hours": 1
  }
]

Estes são limites máximos e valores predefinidos publicados por cada fornecedor e consultados em agosto de 2026, não valores medidos. Eles são relevantes por um motivo: mostram durante quanto tempo uma credencial exposta continua a funcionar enquanto você ainda tenta descobrir que ela foi exposta. Os tokens de curta duração na parte inferior do gráfico duram 1 hora cada, e o SDK os atualiza; portanto, a curta duração não acrescenta nenhum custo operacional. Uma role assumida dura 12 horas. Uma key criada com a predefinição de 30 dias continua válida durante 720 horas. É essa credencial que fica num ficheiro do seu servidor durante um mês.

Onde fica a credencial numa VPS

Coloque o segredo num ficheiro que apenas o root possa ler e deixe o systemd entregá-lo ao processo. Esta parte permanece válida entre versões do SDK, por isso vale a pena configurá-la uma vez e corretamente.

sudo useradd --system --home /opt/claude-app --shell /usr/sbin/nologin claudeapp
sudo install -d -m 700 -o root -g root /etc/claude-app
sudo install -m 600 -o root -g root /dev/null /etc/claude-app/env
sudoedit /etc/claude-app/env

O ficheiro contém linhas simples no formato KEY=value. Não use export, aspas nem sintaxe de shell, porque o systemd analisa o ficheiro diretamente, em vez de o executar através de uma shell.

ANTHROPIC_API_KEY=sk-ant-api03-REPLACE-ME
CLAUDE_MODEL=REPLACE-ME

[Unit]
Description=Claude API service
After=network-online.target

[Service]
User=claudeapp
EnvironmentFile=/etc/claude-app/env
ExecStart=/opt/claude-app/venv/bin/python -m claude_app
Restart=on-failure

[Install]
WantedBy=multi-user.target

O systemd lê EnvironmentFile= como root, antes de mudar para User=claudeapp. Assim, a conta do serviço nunca precisa de ter acesso de leitura ao ficheiro. O modo 600, com o ficheiro pertencente ao root, é suficiente. Por isso, o comando install acima define essas permissões. Inicie o serviço com sudo systemctl enable --now claude-app. Em seguida, confirme com systemctl status claude-app que a unidade chegou ao estado active (running), em vez de reiniciar continuamente.

Há quatro coisas a evitar. Cada uma tem um motivo que pode verificar diretamente:

• Não escreva a chave com Environment= dentro do ficheiro da unidade. Uma unidade em /etc/systemd/system pode ser lida por qualquer utilizador. Por isso, systemctl cat claude-app devolve o segredo a qualquer utilizador local.
• Não faça commit do ficheiro. .gitignore impede que um ficheiro novo entre num commit, mas não faz nada relativamente a um ficheiro que já foi incluído. O histórico do git mantém tudo o que recebeu.
• Não inclua o segredo numa imagem de contentor. As linhas ENV e os valores --build-arg ficam registados nas camadas da imagem, e docker history --no-trunc devolve-os. Apagar o ficheiro numa camada posterior não o remove da camada anterior. Em vez disso, passe os segredos no momento da execução com --env-file ou use um ficheiro montado.
• Não considere o ambiente do processo privado em relação ao root. sudo tr '\\0' '\\n' < /proc/$(pgrep -u claudeapp -f claude_app | head -1)/environ devolve a chave. O objetivo é manter o segredo afastado de todas as outras contas do sistema, não do root, que pode lê-lo independentemente da configuração.

Este último ponto define o limite do que esta configuração oferece. Uma variável de ambiente é um contentor adequado para um segredo quando apenas o serviço e o root lhe podem aceder. É o contentor errado quando o processo executa código que não escreveu, porque qualquer código que o processo consiga executar pode ler o próprio ambiente. Manter os segredos fora do alcance de um agente de IA aborda esse caso. Trata-se de um problema diferente, com uma resposta diferente.

Como faço a rotação da chave sem indisponibilidade?

Faça a rotação primeiro e revogue a chave antiga depois.

1. Crie a nova chave na Console, no mesmo workspace da chave antiga.
2. Grave-a em /etc/claude-app/env com sudoedit.
3. Execute sudo systemctl restart claude-app.
4. Confirme que o serviço está a responder aos pedidos e, em seguida, revogue a chave antiga na Console.

EnvironmentFile é lido quando a unidade arranca, por isso um processo em execução mantém o valor que recebeu no arranque. systemctl daemon-reload volta a ler os ficheiros da unidade, mas não altera o ambiente de um processo em execução. Por isso, apenas um restart aplica a nova chave. Revogar a chave no passo 1, em vez do passo 4, provoca uma indisponibilidade que dura até ao passo 3.

As outras três opções fazem a rotação no fornecedor. Um utilizador IAM suporta duas access keys ativas em simultâneo. Crie a segunda, distribua-a e elimine a primeira. Uma chave de service account do Google roda da mesma forma. Uma chave Foundry é regenerada no portal e invalida imediatamente a antiga. Por isso, grave o novo valor antes de clicar. Os tokens Entra e os tokens Anthropic federados não precisam de rotação. Esse é o principal argumento para os utilizar quando possível.

Enquanto estiver na Console, defina um limite de gastos para o workspace. Uma chave exposta gera custos antes de causar qualquer outro problema, e definir um limite para os gastos de um agente num VPS explica os controlos disponíveis.

Por que o meu cliente retorna 401 ou 403?

401 com authentication_error na API direta. A chave está incorreta, foi revogada ou expirou. A expiração é o caso que mais passa despercebido, porque o código não mudou e o pedido funcionou ontem. Verifique a coluna de expiração da chave no Console ou leia expires_at na Admin API, onde o valor é null para chaves sem expiração.

O SDK ignora a configuração de federação e usa uma chave. ANTHROPIC_API_KEY e ANTHROPIC_AUTH_TOKEN têm precedência sobre a federação na ordem de prioridade das credenciais, portanto qualquer um dos dois a sobrepõe. O detalhe importante é que uma variável exportada como uma string vazia continua a ocupar o seu lugar. Assim, ANTHROPIC_API_KEY="" faz o SDK autenticar com uma chave vazia em vez de continuar para a credencial seguinte. Use unset ANTHROPIC_API_KEY.

401 com a mensagem simples Authentication failed na federação. Essa mensagem é deliberadamente igual para todas as causas possíveis, para que um cliente não possa testar a configuração das regras lendo o texto do erro. O motivo real fica registado na página do histórico de autenticação no Console. Comece por aí em vez de tentar adivinhar o problema no JWT.

403 no Foundry. O token foi autenticado, mas a sua conta Azure não tem uma função que permita fazer a chamada. Atribua uma função Azure RBAC, como Foundry User (anteriormente Azure AI User) ou Cognitive Services User, à identidade que faz o pedido.

Qualquer erro no Bedrock. Execute aws sts get-caller-identity primeiro como o utilizador do serviço. O comando indica se o sistema tem credenciais AWS utilizáveis, separando um problema de credenciais de um problema de acesso ao modelo ou de uma região incorreta. O acesso ao modelo é concedido por região na consola AWS. É fácil ativá-lo numa região e fazer a chamada noutra.

FAQ

Preciso de uma chave de API da Anthropic para usar o Claude no Bedrock ou no Vertex?

Não. No Amazon Bedrock, o SDK assina cada pedido com credenciais da AWS através do SigV4. No Google Cloud, envia um token de acesso do Google obtido através do Application Default Credentials. Nenhuma destas configurações usa um segredo emitido pela Anthropic. O consumo é faturado à conta cloud, e não à Anthropic. É também por isso que uma chave da Anthropic deixada em ANTHROPIC_API_KEY representa um risco nesses hosts: um cliente genérico apontado para um endpoint cloud vai enviá-la para esse endpoint.

O Claude está disponível no Azure?

Sim, através do Microsoft Foundry, anteriormente denominado Azure AI Foundry. Crie um recurso do Foundry, implemente nele um modelo Claude e faça chamadas a https://{resource}.services.ai.azure.com/anthropic/v1/messages com uma chave emitida pelo Azure num cabeçalho api-key ou com um token bearer do Microsoft Entra. O consumo é faturado através do Azure Marketplace em Claude Consumption Units. O campo model no corpo do pedido deve conter o nome da sua implementação. Esse nome só coincide com o identificador do modelo até mudar o nome de uma implementação.

Onde devo armazenar a chave de API do Claude num servidor Linux?

Num ficheiro pertencente a root, com o modo 600, carregado através de EnvironmentFile= numa unidade systemd. O systemd lê esse ficheiro como root antes de mudar para o User= da unidade. Assim, a conta de serviço não precisa de acesso ao ficheiro. Mantenha-o fora do repositório, fora do próprio ficheiro da unidade, que é legível por todos e é apresentado por systemctl cat, e fora das camadas de imagens de contentores, porque docker history --no-trunc mostra novamente tudo o que for definido com ENV ou --build-arg.

Por que motivo o meu pedido à API do Claude começou a devolver 401 quando nada mudou?

A causa mais comum é uma chave que atingiu a data de expiração definida quando foi criada. A expiração é definida na criação e não pode ser alterada posteriormente. As chaves de curta duração expiram sem aviso por email. Uma chave expirada não pode ser reativada. Crie uma substituta, escreva-a no ficheiro de ambiente, reinicie o serviço e revogue a chave antiga depois. Se a chave estiver efetivamente válida, confirme que uma credencial antiga não a está a substituir: ANTHROPIC_API_KEY definido como uma cadeia vazia continua a ter precedência sobre todas as outras fontes de credenciais.