SSD Nodes Learn Hosting plans →
Guias Matt ConnorPor Matt Connor

Como autenticar a Claude API: chave, Bedrock e nuvem

Veja como autenticar um cliente Claude API em um VPS com chave Anthropic, AWS IAM, Google ADC ou Microsoft Entra e guardar credenciais do servidor com segurança.

Rotas de autenticação da API Claude

A autenticação da API Claude resume-se a uma decisão: qual credencial o cliente coloca na rede. A Anthropic lista a API Claude direta e cinco plataformas de cloud: Amazon Bedrock, Claude Platform on AWS, Claude Models on Google Cloud (Google managed), Claude Models on Google Cloud (Anthropic managed) e Microsoft Foundry. A API Anthropic direta aceita uma chave de API ou um token de curta duração num cabeçalho Authorization: Bearer e continua a aceitar chaves de API no cabeçalho legado x-api-key. O Amazon Bedrock suporta a assinatura de pedidos AWS e chaves de API do Bedrock; nesta configuração não existe nenhuma chave Anthropic. 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. As quatro secções abaixo abrangem estas configurações de credenciais, com as ofertas geridas pela Anthropic para AWS e Google Cloud explicadas juntamente com as ofertas correspondentes das respetivas clouds.

Este guia destina-se a integrar um SDK (software development kit) num serviço executado 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 indicar ao Claude Code para usar Bedrock ou Vertex. Se o serviço ainda não existir, crie-o primeiro com criar a primeira aplicação da API Claude numa VPS e volte aqui para configurar a credencial.

Tudo o que é apresentado abaixo foi verificado com base na documentação da plataforma Anthropic em agosto de 2026 e novamente com base na documentação de cada fornecedor em 16 de outubro de 2026; os detalhes de acesso a modelos do Bedrock foram novamente verificados com base na documentação da AWS em 19 de outubro de 2026. As páginas da Anthropic sobre as quatro rotas, as chaves de API e as versões da API foram novamente verificadas em 27 de outubro de 2026. As páginas da Anthropic sobre o Microsoft Foundry, os dois endpoints do Bedrock, a rota gerida pelo Google, o Claude Platform on AWS, a autenticação, a Workload Identity Federation e as versões da API foram novamente verificadas em 10 de novembro de 2026, juntamente com o changelog do SDK Ruby. Os identificadores de modelos, preços, versões dos SDKs e formatos dos endpoints mudam com o tempo. Por isso, este guia liga 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. As solicitações vão para o endpoint Messages no host da API da Anthropic, e cada solicitação 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 de modelos da Anthropic. Uma resposta válida é um JSON que contém um array content e um objeto usage. Uma chave incorreta ou expirada retorna HTTP 401 com authentication_error. A ausência do cabeçalho anthropic-version causa uma falha diferente, porque esse cabeçalho é obrigatório em todas as solicitações; os SDKs o definem automaticamente. Em outubro de 2026, a documentação da Anthropic apresenta Authorization: Bearer como a principal forma de enviar a chave e chama x-api-key de legado, mas ambos são aceitos, portanto o comando acima continua funcionando. As versões principais atuais dos SDKs também enviam a chave como Authorization: Bearer, portanto um proxy ou gateway que lê X-Api-Key precisa ser atualizado quando você fizer o upgrade. A versão 2023-06-01 no comando ainda é aceita; a versão mais recente da API da Anthropic é 2026-10-21, que essas versões dos SDKs enviam por padrão e que rejeita alguns parâmetros de solicitação antigos, como temperature.

A criação do cliente é a mais simples dessas configurações, porque não há nada para construir. Cada SDK oficial lê ANTHROPIC_API_KEY do ambiente por conta própria.

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 com a chave. Os nomes dos modelos mudam conforme um cronograma que você não controla, e fazer o redeploy do código para editar uma única string é trabalho evitável.

As chaves são criadas no Console, onde você escolhe uma expiração no momento da criação: predefinições de 3 horas, 1 dia, 7 dias ou 30 dias, uma duração personalizada ou Never, sujeitas à política de expiração máxima da sua organização. A expiração é definida na criação e não pode ser alterada depois. A Anthropic envia um email ao criador da chave antes de uma chave de longa duração expirar, mas uma chave com vida útil curta expira sem qualquer email de aviso. Uma chave expirada retorna 401 e não pode ser reativada; portanto, a correção é sempre criar uma nova chave.

Não há uma região para escolher na API direta, e a cobrança vai diretamente para a sua organização na Anthropic. Os workspaces limitam uma chave a um projeto, que é a forma mais clara de saber quanto um único serviço gasta. Limite a chave de um servidor ao workspace ao criá-la: uma chave de conta pessoal ou de serviço que não esteja limitada a um workspace precisa enviar um cabeçalho anthropic-workspace-id em todas as solicitações, ou a API responde 400 com invalid_request_error. Para um serviço, escolha uma chave de conta de serviço, porque uma chave pessoal deixa de funcionar quando a pessoa que a criou sai da organização. Para os cálculos por trás dessa cobrança, consulte como os preços da API por token se comparam a uma assinatura.

Há mais uma opção que pertence a esta seção, porque ela remove completamente o segredo estático. A Workload Identity Federation permite que uma carga de trabalho troque um token OpenID Connect (OIDC) de um provedor de identidade em que você já confia por um token Anthropic de curta duração em POST /v1/oauth/token, e o SDK atualiza esse token antes que ele expire. Nenhuma string sk-ant-api... é criada ou copiada em lugar algum. Isso funciona bem com Kubernetes, GitHub Actions e VMs na nuvem, que já carregam uma identidade da plataforma. Um VPS comum geralmente não tem esse emissor; nesse caso, uma chave de API em um arquivo é a resposta correta, e o restante deste guia trata a configuração dessa forma.

Rota 2: credenciais da AWS no Amazon Bedrock

No Bedrock, não tem nenhuma chave da Anthropic. Com credenciais da AWS, o SDK assina cada pedido HTTP com o AWS Signature Version 4 (SigV4), e a AWS decide se esse chamador 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 coisa ao usar SigV4. Para SigV4, o SDK resolve as credenciais do construtor, as credenciais do ambiente e a cadeia padrão de credenciais da AWS; a seleção da região é separada. No cliente Python AnthropicBedrock, uma chave de API do Bedrock fornecida como api_key ou através de AWS_BEARER_TOKEN_BEDROCK gera ValueError se também passar aws_access_key, aws_secret_key, aws_session_token ou aws_profile. Sem esses argumentos explícitos, a chave seleciona autenticação bearer em vez da cadeia de credenciais da AWS. O cliente TypeScript dá precedência à chave de API do Bedrock sobre as credenciais explícitas da AWS. O comando STS não testa a autenticação bearer.

Na construção do cliente, muda a classe e um argumento.

from anthropic import AnthropicBedrock

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

AnthropicBedrock controla a integração InvokeModel do Bedrock. Em outubro de 2026, a Anthropic também documenta o Claude no Amazon Bedrock, com um endpoint da Messages API em https://bedrock-mantle.{region}.api.aws/anthropic/v1/messages para o Claude Opus 4.7 e modelos posteriores, acedido através de um cliente AnthropicBedrockMantle do mesmo pacote. Ele aceita credenciais da AWS e tokens bearer do Bedrock; os requisitos de acesso aos modelos diferem entre os dois endpoints, conforme explicado abaixo.

Acompanhe a atualização nessa linha pip install -U. Em 27 de outubro de 2026, o SDK mais recente envia por predefinição a versão de API 2026-10-21, inclusive através do Bedrock, e a Anthropic documenta que os IDs de modelo com versão no ARN que lista para o Claude Opus 4.6 e versões anteriores não suportam essa versão no Bedrock e podem devolver um erro 400. Se um serviço chamar um desses modelos, mantenha o SDK na versão que ele usa atualmente e fixe essa versão, ou migre primeiro o serviço para um modelo Claude 4.7 ou posterior.

A região deixa de ser apenas configuração decorativa. Os endpoints do Bedrock são específicos de cada região, os modelos Claude disponíveis diferem entre regiões e a região faz parte da assinatura SigV4, portanto uma assinatura calculada para uma região é rejeitada por outra. Defina AWS_REGION explicitamente no ambiente do serviço, porque os SDKs não têm o mesmo comportamento quando esse valor é omitido. Conforme documentado em outubro de 2026, o cliente Python AnthropicBedrock lê AWS_REGION ou AWS_DEFAULT_REGION, depois a região da sua sessão boto3 ou do perfil da AWS, incluindo ~/.aws/config, e gera ValueError se nenhum valor for resolvido. O cliente TypeScript lê AWS_REGION, usa us-east-1 como alternativa quando esse valor não está definido e não lê ~/.aws/config para determinar a região. É por isso que a AWS CLI pode listar os modelos Claude com sucesso no mesmo servidor onde um processo Node chama a região errada: a CLI leu o seu ficheiro de configuração e o cliente não.

Numa instância EC2, anexa uma função IAM (gestão de identidade e acesso) e 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, tem de escolher entre um par de chaves de acesso de longa duração de um utilizador IAM armazenado no servidor, que pertence à mesma categoria de segredo que uma chave da Anthropic, e a 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 chaves de API do Bedrock, que são tokens bearer passados através de AWS_BEARER_TOKEN_BEDROCK, e a AWS documenta dois tipos. Uma chave de curta duração é válida por até 12 horas, ou pela duração da sessão que a gerou se esta for menor, herda as permissões da identidade IAM que a gerou e é o tipo recomendado pela AWS para produção. Uma chave de longa duração permanece válida até à data de expiração escolhida durante a criação, por exemplo 30 ou 90 dias com --credential-age-days, ou não expira se esse parâmetro da API for omitido; a Console cria um utilizador IAM associado, e a AWS recomenda esse tipo apenas para exploração. Uma chave de longa duração funciona apenas na região onde foi gerada; usá-la noutra região devolve Credential should be scoped to a valid region.

A faturação é feita na sua conta AWS, e não junto da Anthropic, o que normalmente é a principal razão para escolher esta opção. Os endpoints regionais têm um custo adicional de 10% em relação ao endpoint global, conforme documentado em outubro de 2026. O Claude Platform on AWS é um produto separado: a Anthropic opera-o, a AWS cobra-o através do AWS Marketplace e a autenticação é feita com SigV4 ou com uma chave de API gerada na AWS Console, porque as chaves da Claude Console não funcionam nesse serviço, através de um cliente AnthropicAWS que a Anthropic marca como beta. Vale a pena reconhecer um erro do Bedrock porque ele 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. Esse é um problema de encaminhamento do modelo, e nenhuma alteração nas credenciais o corrige.

Rota 3: credenciais Google no Vertex AI

A documentação da Anthropic chama agora esta rota Claude Models on Google Cloud (Google managed), que a Google executa como parte da sua Agent Platform, o novo nome da Google para o que evoluiu a partir do Vertex AI. O host aiplatform.googleapis.com, o extra anthropic[vertex] e a classe AnthropicVertex apresentados abaixo não mudam.

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

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

Numa workstation, esse login escreve $HOME/.config/gcloud/application_default_credentials.json e o processo termina. Num servidor, evite armazenar as credenciais de um utilizador humano; o comando também suporta a impersonation de uma service account. Fora do Google Cloud, também não existe um metadata server da Google, por isso use GOOGLE_APPLICATION_CREDENTIALS para indicar ao ADC um ficheiro de configuração de Workload Identity Federation ou um ficheiro de chave de service account. Um ficheiro JSON de chave de service account é um segredo de longa duração e requer exatamente o tratamento descrito mais adiante neste guia. Dentro do Google Cloud, associe uma service account à VM e não haverá nenhum ficheiro para proteger. A identidade encontrada pelo ADC precisa de uma função IAM que inclua a permissão aiplatform.endpoints.predict, como Agent Platform User (roles/aiplatform.user).

from anthropic import AnthropicVertex

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

Há duas diferenças quando se desce do SDK para HTTP direto. O identificador do modelo sai do corpo do pedido e passa para o caminho do URL, e anthropic_version sai do cabeçalho e passa para o corpo. Em 27 October 2026, a documentação da Anthropic aceita nesse campo vertex-2023-10-16 ou a versão de API mais recente 2026-10-21. A credencial é um access token normal da Google. No comando abaixo, gcloud auth print-access-token usa o login próprio da CLI gcloud em vez do ADC; por isso, execute gcloud auth login ou gcloud init primeiro na máquina onde o testa.

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 multi-regionais, e um nome como us-east5 fixa uma única região. Em October 2026, a Anthropic documenta endpoints de região única apenas para Claude Sonnet 4.6 e versões anteriores; os modelos mais recentes usam endpoints globais ou multi-regionais. Os endpoints multi-regionais e regionais custam 10% mais do que os globais, conforme documentado em October 2026. A faturação é feita através do projeto Google Cloud, por isso as quotas e as faturas são da Google.

Em 27 October 2026, a Anthropic também documenta uma segunda oferta Google Cloud, com um formato de pedido diferente. Em Claude Models on Google Cloud (Anthropic managed), a Anthropic opera a própria Claude API em claude.googleapis.com, acedida através de um cliente AnthropicGoogleCloud. A autenticação continua a usar credenciais Google Cloud, incluindo ADC, mas o pedido tem o formato da API direta: model permanece no corpo e a versão segue no cabeçalho anthropic-version. O acesso é fornecido pelas suas próprias funções IAM (roles/claude.user e relacionadas), a configuração cria uma nova organização Anthropic para o projeto e a utilização é faturada através do Google Cloud Marketplace. Se os URLs dos seus pedidos contiverem aiplatform e terminarem em :rawPredict, está na rota gerida pela Google descrita nesta secção.

Rota 4: o Microsoft Foundry é a rota do Azure

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

Funcionam duas credenciais. A primeira é uma chave emitida pelo Azure, disponível no separador Details da implementação no portal Foundry, enviada num cabeçalho api-key ou x-api-key. A segunda é um token Microsoft Entra. Esta é 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 coincidem. Deixam de coincidir assim que atribui um nome personalizado à implementação. Esta é a causa habitual de um erro Deployment not found num pedido que, de resto, está correto. Os SDKs Python e TypeScript leem ANTHROPIC_FOUNDRY_API_KEY e ANTHROPIC_FOUNDRY_RESOURCE do ambiente. De acordo com a documentação de 10 de novembro de 2026, o Foundry suporta os sete SDKs oficiais: C#, Go, Java, PHP, Python, Ruby e TypeScript. O Go utiliza um pacote foundry dedicado (go get github.com/anthropics/anthropic-sdk-go/v2/foundry), e o Ruby passou a ter um Anthropic::FoundryClient dedicado na versão 2.5.0 do gem, publicada em 4 de novembro de 2026. Antes dessa versão, o código Ruby tinha de apontar o cliente genérico para o URL base do Foundry.

Apontar um cliente genérico para o URL base do Foundry continua a ter um risco específico, tanto no código Ruby escrito antes da versão 2.5.0 como na CLI ant, que os próprios exemplos da Anthropic para Foundry utilizam dessa forma. Se não passar explicitamente as credenciais ao cliente genérico e ANTHROPIC_API_KEY ou ANTHROPIC_AUTH_TOKEN ainda estiver definida no ambiente, o cliente utiliza esse valor e envia a sua credencial Anthropic para um endpoint Microsoft. Remova a variável do ambiente ou passe explicitamente a chave ou o token do Foundry ao cliente. Em Ruby, mudar para Anthropic::FoundryClient, que aceita a chave do Foundry ou um fornecedor de tokens Entra, é a solução mais simples. Um token de acesso Entra recebe um tempo de vida predefinido aleatório entre 60 e 90 minutos. Por isso, um processo de longa duração tem de renová-lo, em vez de guardar um único token no arranque.

Quanto tempo permanece válida a credencial no seu servidor?

GráficoDocumented credential lifetime by route, hours
Os dados por trás deste gráfico
[
  {
    "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 short-term API key",
    "max_lifetime_hours": 12
  },
  {
    "label": "Entra ID access token, default upper bound",
    "max_lifetime_hours": 1.5
  },
  {
    "label": "Federated Anthropic token, default",
    "max_lifetime_hours": 1
  }
]

Estes são limites máximos e valores predefinidos publicados por cada fornecedor e consultados em outubro de 2026, não valores medidos. São importantes por uma razão: indicam durante quanto tempo uma credencial exposta continua a funcionar enquanto ainda está a determinar que foi exposta. O token Anthropic federado no fim do gráfico permanece válido por até 1 horas por predefinição, limitado também a duas vezes o tempo de validade restante do token do fornecedor de identidade. Um token de acesso do Microsoft Entra não tem um valor predefinido único: a Microsoft atribui a cada token uma validade aleatória entre 60 e 90 minutos (75 em média), apresentada no gráfico no limite superior de 1.5 horas. Esse valor predefinido também varia conforme o cliente, o recurso e o facto de o Conditional Access estar ativado no tenant. Quando o cliente e o recurso suportam Continuous Access Evaluation, o Entra pode prolongar a validade para 24 a 28 horas e revogar o token quase em tempo real em eventos como a desativação da conta. Uma política de validade de tokens do tenant pode definir qualquer valor entre 10 minutos e 23:59:59. Os SDKs atualizam automaticamente os tokens Anthropic federados; no Foundry, configure um fornecedor de tokens Entra para atualizar os tokens em vez de passar uma string de token fixa. Uma regra de federação pode definir a sua própria validade de token entre um minuto e 24 horas. O assistente Connect workload da Console preenche 10 minutos por predefinição. Por isso, leia a regra em vez de assumir o valor predefinido. Uma role assumida e uma chave de API de curto prazo do Bedrock têm ambas 12 horas. Uma chave de API de longo prazo do Bedrock não aparece no gráfico porque não tem um limite máximo fixo: permanece válida até à data de expiração escolhida quando foi criada ou não expira se CredentialAgeDays for omitido da chamada da API. Por esse motivo, a AWS recomenda-a apenas para exploração. Uma chave criada com a predefinição de 30 dias permanece válida durante 720 horas. É essa a credencial que fica num ficheiro do servidor durante um mês.

Onde a credencial fica em um VPS

Coloque o segredo em um arquivo que somente root possa ler e deixe o systemd entregá-lo ao processo. Esta parte permanece válida em todas as versões do SDK, portanto 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 arquivo contém linhas simples no formato KEY=value. Sem export, sem aspas e sem sintaxe de shell, porque o systemd faz o próprio parsing em vez de executar o conteúdo por meio de um 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, portanto a conta do serviço nunca precisa de acesso de leitura ao arquivo. O modo 600 com o arquivo pertencendo a root é suficiente. Por isso, o comando install acima define essas permissões. Inicie-o com sudo systemctl enable --now claude-app e confirme com systemctl status claude-app que a unidade chegou a active (running) em vez de reiniciar em loop.

Evite estas quatro coisas. Cada uma tem um motivo que você pode verificar:

  • Não grave a chave com Environment= dentro do arquivo da unidade. Uma unidade em /etc/systemd/system pode ser lida por qualquer usuário, portanto systemctl cat claude-app exibe o segredo para qualquer usuário local.
  • Não faça commit do arquivo. .gitignore mantém um arquivo novo fora de um commit, mas não faz nada com um arquivo que já foi incluído, porque o histórico do git mantém tudo o que recebeu.
  • Não inclua o segredo em uma imagem de container. Os valores de ENV permanecem na configuração da imagem, e os argumentos de build ficam visíveis no histórico da imagem ou nos metadados de proveniência. Excluir o arquivo em uma camada posterior não o remove da camada anterior. Passe os segredos em tempo de execução com --env-file ou use um arquivo montado.
  • Não trate o ambiente do processo como privado em relação a root. sudo cat /proc/$(pgrep -u claudeapp -f claude_app | head -1)/environ | tr '\0' '\n' exibe a chave. O próprio comando que lê o arquivo precisa de sudo; um redirecionamento de entrada do shell é executado antes de sudo e usa as permissões da sua conta atual. O objetivo é manter o segredo longe de todas as outras contas do servidor, não de root, que pode lê-lo independentemente do que você faça.

Esse último ponto define o limite do que este projeto oferece. O arquivo acessível apenas por root protege a chave armazenada, mas qualquer código executado como a conta do serviço pode ler o ambiente do processo, e os processos filhos o herdam. Esse é o container errado quando o processo executa código que você não escreveu, porque tudo o que o processo pode executar também pode ler o próprio ambiente. Mantendo os segredos fora do alcance de um agente de IA aborda esse caso, que é 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 por último. O reinício de um único serviço abaixo interrompe brevemente o serviço. Para manter a disponibilidade, é necessária outra instância para tratar os pedidos durante o reinício.

  1. Crie a nova chave na Console, no mesmo workspace da chave antiga.
  2. Escreva-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 inicia. 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 reinício aplica a nova chave. Revogar a chave no passo 1, em vez de no passo 4, provoca uma indisponibilidade que dura até ao passo 3.

As credenciais de cloud são rodadas no fornecedor. Um utilizador IAM suporta duas chaves de acesso ativas em simultâneo. Crie a segunda, faça o deploy e elimine depois a primeira. Uma chave de service account do Google roda da mesma forma. Um recurso Foundry contém duas chaves. Regenerar uma faz com que o valor antigo deixe de funcionar imediatamente. Por isso, passe o serviço para a outra chave antes de regenerar a chave que estava a utilizar. Os tokens Entra e os tokens Anthropic federados não exigem rotação manual. Esse é o argumento mais forte para os utilizar quando possível.

Enquanto estiver na Console, defina um limite de gastos para o workspace. Uma chave exposta é dispendiosa antes de ser qualquer outra coisa, e limitar o que um agente num VPS pode gastar explica os controlos disponíveis.

Por que o meu cliente devolve 401 ou 403?

401 com authentication_error na API direta. A chave está errada, foi revogada ou ultrapassou a validade. A validade é o que mais costuma passar despercebido, porque o código não mudou e o pedido funcionou ontem. Verifique a coluna de validade da chave na Console ou leia expires_at na Admin API, onde o valor é null para chaves sem validade. Uma chave pessoal também deixa de funcionar quando o respetivo proprietário sai da organização.

O SDK ignora a configuração de federation e usa uma chave. ANTHROPIC_API_KEY e ANTHROPIC_AUTH_TOKEN têm precedência sobre federation na ordem de prioridade das credenciais, por isso qualquer um dos dois a oculta. O caso mais específico é este: uma variável exportada como cadeia vazia continua a ocupar a sua posição, pelo que ANTHROPIC_API_KEY="" faz o SDK autenticar com uma chave vazia em vez de passar para a opção seguinte. Use unset ANTHROPIC_API_KEY.

401 com a mensagem simples Authentication failed em federation. Essa mensagem é deliberadamente idêntica para todas as causas possíveis, para impedir que um cliente descubra a configuração das regras através do texto do erro. O motivo real fica registado na página do histórico de autenticação na Console. Comece por aí, em vez de tentar adivinhar a causa a partir do JWT.

403 no Foundry. O token foi autenticado, mas a sua conta Azure não tem uma função que permita 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. Para autenticação SigV4, execute primeiro aws sts get-caller-identity como o utilizador de serviço. O comando indica se o servidor tem credenciais AWS utilizáveis, permitindo separar um problema de credenciais de um problema de acesso ao modelo ou de uma região incorreta. Em 29 October 2026, a AWS ativa o acesso a muitos modelos na primeira utilização em regiões comerciais com as permissões necessárias do AWS Marketplace, mas alguns modelos exigem acesso separado ao nível da conta. Os modelos Anthropic chamados através da rota InvokeModel exigem primeiro um formulário de caso de utilização único por conta (ou uma vez para toda uma AWS Organization, embora as regiões com opt-in o exijam novamente) e, até ser aprovado, a chamada devolve AccessDeniedException. A AWS documenta que o formulário não se aplica ao endpoint bedrock-mantle. A primeira chamada a um modelo numa conta também faz com que o Bedrock inicie a subscrição do AWS Marketplace em segundo plano, e essa subscrição requer uma identidade com as permissões aws-marketplace:Subscribe, aws-marketplace:Unsubscribe e aws-marketplace:ViewSubscriptions. A ausência dessas permissões não faz necessariamente falhar a primeira chamada: a AWS documenta que as chamadas podem funcionar durante até 15 minutes enquanto a subscrição é configurada e, quando a subscrição falha, as chamadas seguintes devolvem o mesmo AccessDeniedException. Um serviço que funcionou durante os primeiros minutes e depois começou a falhar aponta para este problema, não para as credenciais. Depois de atribuir as permissões, a AWS permite até 2 minutes para a conclusão da subscrição. Um modelo que não é disponibilizado na região chamada falha, por melhores que sejam as credenciais.

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 as solicitações com credenciais da AWS usando SigV4 ou envia uma chave de API do Bedrock. No Google Cloud, ele envia um token de acesso do Google obtido por meio do Application Default Credentials. Nenhum segredo emitido pela Anthropic existe em nenhuma das duas configurações. O uso é faturado na conta de nuvem, e não pela Anthropic. Por isso, uma chave da Anthropic deixada em ANTHROPIC_API_KEY também representa um risco nesses hosts: um cliente genérico apontado para um endpoint de nuvem vai enviá-la para lá sem problemas.

O Claude está disponível no Azure?

Sim, por meio do Microsoft Foundry, anteriormente chamado Azure AI Foundry. Você cria um recurso do Foundry, implanta um modelo Claude nele e chama https://{resource}.services.ai.azure.com/anthropic/v1/messages usando uma chave emitida pelo Azure em um cabeçalho api-key ou um token bearer do Microsoft Entra. O uso é faturado pelo Azure Marketplace em Claude Consumption Units. O campo model no corpo da solicitação deve conter o nome da implantação. Esse nome só corresponde ao identificador do modelo se você manteve o nome padrão ao criar a implantação. O nome não pode ser alterado depois.

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

Em um arquivo pertencente a root, com modo 600, carregado por meio de EnvironmentFile= em uma unidade systemd. O systemd lê esse arquivo como root antes de mudar para o User= da unidade. Assim, a conta de serviço não precisa ter acesso a ele. Mantenha o arquivo fora do repositório, fora do próprio arquivo da unidade, que pode ser lido por todos e é exibido por systemctl cat, e fora da configuração da imagem do contêiner, das camadas e dos metadados de build.

Por que minha solicitação à API do Claude começou a retornar 401 se nada mudou?

Uma chave que chega à data de expiração definida quando foi criada retorna 401. A expiração é definida na criação e não pode ser editada depois. Chaves de curta duração expiram sem enviar um email de aviso. Uma chave expirada não pode ser reativada. Portanto, crie uma substituta, grave-a no arquivo de ambiente, reinicie o serviço e revogue a chave antiga depois. Se a chave estiver definitivamente válida, verifique se uma credencial obsoleta não está ocultando-a: ANTHROPIC_API_KEY definido como uma string vazia ainda tem precedência sobre as fontes de federação e de perfil abaixo dele.

Este artigo foi útil?

#claude#api#authentication#bedrock#vertex#secrets-management