Erro de autenticação: qual chave API Anthropic o seu projeto está pedindo?

Fala aí, beleza? Se você tem assinatura do Claude, uma chave criada no Console, um gateway no meio do caminho e ainda um servidor MCP configurado, o 401 que aparece no terminal não está te dizendo qual dessas credenciais falhou

E aí começa a caçada errada: a pessoa cria uma chave nova, cola no projeto e o erro continua igualzinho

A chave que você pega no Console da plataforma (platform.claude.com > Settings > API keys, aquela que começa com sk-ant-) dá acesso à Claude API

Mas assinatura, gateway, provedor de nuvem, servidor MCP e pipeline de CI pedem credenciais PRÓPRIAS, cada um do seu jeito

Bora separar isso de vez e descobrir qual delas o erro está reclamando?

As credenciais que podem estar no caminho (e onde cada uma vale)

Antes do diagnóstico, o mapa

Cada cenário abaixo pede uma credencial diferente, e misturar os dois é justamente o que gera o erro de autenticação sem explicação

Pré-inscrição Formação Claude Code

Domine o Claude Code do básico ao avançado

Você vai aprender a criar sistemas completos com Claude Code, sem precisar ser programador. Inscreva-se para ter acesso a um desconto de lançamento e bônus especiais!

Quero minha vaga

Duas coisas que valem grifar aqui

A primeira: o Claude Code está incluso em todos os planos pagos e divide o MESMO pool de limites de uso do resto do plano, ou seja, terminal e chat consomem da mesma cota

A segunda: a chave de API é cobrança separada da assinatura

Uma assinatura paga do Claude (Pro, Max, Team ou Enterprise) não inclui acesso à Claude API nem ao Console, o acesso de API é contratado à parte, com créditos pré-pagos que cobrem API, Workbench e o próprio Claude Code

Onde as variáveis de API key NÃO valem:

Esse detalhe economiza muita hora perdida

O apiKeyHelper, o ANTHROPIC_API_KEY e o ANTHROPIC_AUTH_TOKEN valem para a CLI e para as superfícies que embrulham a CLI: extensão do VS Code, Agent SDK e GitHub Actions

O Claude Desktop e as sessões na nuvem usam OAuth exclusivamente

Eles não chamam o apiKeyHelper e não leem essas variáveis de ambiente, então ficar exportando variável no shell esperando que o app desktop obedeça é tempo jogado fora 🙂

Como descobrir qual credencial está ativa agora

Aqui vai a sequência de diagnóstico

A lógica é sempre a mesma: primeiro você descobre PARA ONDE a requisição vai, depois qual credencial aquela superfície aceita

1. Rode /status dentro do Claude Code, esse comando mostra qual credencial está ativa naquele momento. O erro comum deste passo é ignorar a resposta: se aparece uma linha de API key, a chave aprovada É a credencial ativa
2. Se o /status mostrou linha de API key, NÃO rode /login. O erro comum aqui é exatamente esse, rodar /login achando que troca a credencial, e ela não é substituída por isso
3. Compare com a ordem de precedência das credenciais da Anthropic. Uma sessão de gateway dos apps Claude, quando existe, vence essa cadeia (bearer token, API key, apiKeyHelper e perfis não são usados). Abaixo dela vem o apiKeyHelper, depois CLAUDE_CODE_OAUTH_TOKEN, depois o perfil nomeado em ANTHROPIC_PROFILE e, por último, o OAuth da assinatura vindo do /login. Repare que a ANTHROPIC_API_KEY não aparece nomeada nessa lista: o que a documentação afirma sobre ela é uma coisa só, depois de aprovada ela tem precedência sobre o login da assinatura
4. Cheque se alguma variável de provedor de nuvem está setada. Quando CLAUDE_CODE_USE_BEDROCK, CLAUDE_CODE_USE_VERTEX ou CLAUDE_CODE_USE_FOUNDRY está no ambiente, as credenciais do provedor de nuvem vêm primeiro na ordem de escolha, então a chave do Console nem chega a ser consultada
5. Confira se existe ANTHROPIC_API_KEY definida no ambiente. O erro comum: ela ter sido exportada no perfil do shell meses atrás e ninguém lembrar mais disso
6. Identifique como a requisição sai. ANTHROPIC_API_KEY é enviada no cabeçalho X-Api-Key, que é o acesso direto à API da Anthropic, enquanto ANTHROPIC_AUTH_TOKEN é enviada como Authorization: Bearer, que é o caminho de gateways, proxies e roteadores

O comando do passo 1 é literalmente isso, dentro da sessão:

/status

Se a linha que aparece não bate com a credencial que você QUERIA usar, o problema não é a chave, é a ordem

A documentação de autenticação do Claude Code é a referência dessa lista de precedência, vale deixar aberta numa aba enquanto você depura

Tenho assinatura Claude ativa, mas o projeto insiste em cobrar da API

Sintoma: você paga a assinatura, o login está feito, e mesmo assim o consumo vai para a Claude API ou aparece um pedido de chave do nada

Causa: existe uma ANTHROPIC_API_KEY definida no ambiente

Depois de aprovada, essa chave passa na frente do login da assinatura, ou seja, a assinatura simplesmente deixa de ser a credencial usada

E como assinatura paga não inclui acesso à Claude API nem ao Console, você acaba consumindo de um bolso que é cobrado à parte, com os créditos pré-pagos

Solução: remova a variável do ambiente e confira de novo no /status

No shell:

unset ANTHROPIC_API_KEY

No PowerShell:

Remove-Item Env:ANTHROPIC_API_KEY

Como prevenir: se a sua intenção é usar a assinatura, não deixe a chave exportada no perfil do shell

Aquele export colocado uma vez pra testar a API vira uma pegadinha permanente, porque ele volta a valer em toda sessão nova

401 authentication_error que não some depois de reautenticar

Na API da Anthropic, o código HTTP 401 corresponde ao tipo de erro authentication_error

Só que o mesmo 401 tem umas três origens bem diferentes, e é aí que a coisa trava

Sintoma 1: o 401 volta na mesma sessão logo depois de você reautenticar

Solução: rode /logout primeiro, pra limpar por completo o token armazenado, e só então /login

A ordem importa, reautenticar por cima do token velho é o que mantém o erro vivo

Sintoma 2: você usa um apiKeyHelper e o 401 aparece com a mensagem Invalid authentication credentials

Causa: um apiKeyHelper que falha ou não devolve chave faz a requisição chegar à API com credencial placeholder, e ela é rejeitada

O bom é que o /status mostra a saída de erro do script, então dá pra ver o que quebrou sem adivinhação

Sintoma 3: a credencial tem formato válido, parece certinha, e mesmo assim o 401 aparece

Causa: o problema está na conta ou na organização por trás dela

Pode ser credencial revogada há pouco, organização desativada, organização que removeu o seu acesso ou conta desativada

Como prevenir: guarde o valor da chave no ato da criação

Ele começa com sk-ant- e aparece UMA única vez, na hora em que você cria

Na criação também dá pra escopar por workspace e definir expiração, e vale usar isso de forma consciente: chave sem escopo é aquela que ninguém sabe onde está sendo usada quando dá problema 😀

O erro vem de um servidor MCP, não da chave da Anthropic

Sintoma: tudo funciona, até você usar um servidor MCP

Aí a autenticação falha, ou o servidor aparece na lista como conexão falha

Causa: servidores MCP têm credenciais próprias, que não têm nada a ver com a sua chave API da Anthropic

O Claude Code marca um servidor remoto como precisando de autenticação quando ele responde 401 Unauthorized ou 403 Forbidden

E tem um caso que confunde muito: se você configurou um headers.Authorization na mão e o servidor rejeita esse header, o Claude Code reporta a conexão como falha em vez de cair no fluxo OAuth

Ou seja, o header manual BLOQUEIA o caminho que resolveria sozinho

Solução: autentique pelo comando /mcp, que faz a autenticação OAuth desses servidores com login no navegador

/mcp

Se você configurou header manual, confira se aquele token vale pra AQUELE endpoint MCP, ou remova o header pra deixar o OAuth trabalhar

Para credenciais que não são OAuth, dá pra passar valores pelo campo env da configuração do servidor, com expansão de variáveis de ambiente na sintaxe ${VAR} e fallback em ${VAR:-default}

E para esquemas de autenticação que não são OAuth mesmo (Kerberos, tokens curtos, SSO interno), existe o headersHelper: um comando que o Claude Code roda e cujo resultado é mesclado nos headers da conexão

Como prevenir: não reaproveite a chave sk-ant- como header de servidor MCP

Ela não é a credencial daquele serviço, e o resultado vai ser um 401 que parece da Anthropic mas não é

Falha de autenticação em CI, container ou servidor sem navegador

Sintoma: funciona lindamente na sua máquina e quebra no pipeline

Causa: o ambiente de CI não tem login por navegador, então o OAuth interativo não rola

E quase sempre o secret configurado não corresponde ao TIPO de credencial que você quis usar

No GitHub Actions o segredo do repositório se chama ANTHROPIC_API_KEY quando a credencial é uma chave de API, e CLAUDE_CODE_OAUTH_TOKEN quando é o token da assinatura

Tem um detalhe que pega gente boa: esse token pode expirar ou ser invalidado se você fizer logout do Claude Code na sua máquina

O pipeline quebra e ninguém liga uma coisa à outra

Solução: gere de novo o token de longa duração e atualize o segredo do repositório

claude setup-token

Esse comando gera um token OAuth de longa duração da assinatura, guardado como CLAUDE_CODE_OAUTH_TOKEN, pensado justamente pra ambientes sem login por navegador: CI, containers, servidores

Como prevenir: alinhe o nome do secret ao tipo de credencial ANTES de rodar o workflow

Secret com nome de chave guardando token de assinatura é bug garantido, e o log só vai te dizer 401

O projeto roda em Bedrock, Vertex ou Foundry e a chave da Anthropic não serve

Sintoma: a mesma chave sk-ant- que funciona em outro projeto é ignorada ou rejeitada neste aqui

Causa: com CLAUDE_CODE_USE_BEDROCK, CLAUDE_CODE_USE_VERTEX ou CLAUDE_CODE_USE_FOUNDRY setada, as credenciais do provedor de nuvem vêm primeiro na ordem de escolha

Sua chave do Console fica lá, bonita, sem ser consultada

No Amazon Bedrock, por exemplo, a autenticação usa os provedores de credencial padrão da AWS: o arquivo ~/.aws/credentials ou as variáveis AWS_ACCESS_KEY_ID e AWS_SECRET_ACCESS_KEY

Nada de chave da plataforma da Anthropic ali

Solução: defina as variáveis antes de rodar o claude

export CLAUDE_CODE_USE_BEDROCK=1
export AWS_ACCESS_KEY_ID=...
export AWS_SECRET_ACCESS_KEY=...
claude

A outra via é escolher a opção de plataforma de terceiro no prompt de login, que abre um assistente interativo de configuração

Se você não curte configurar variável na mão, esse caminho é bem mais tranquilo

Como prevenir: documente no README do projeto qual provedor está em uso

É o tipo de informação que parece óbvia pra quem configurou e vira mistério total pra quem entra depois

Conclusão

O método cabe em uma frase: primeiro descubra pra ONDE a requisição vai, depois qual credencial aquela superfície aceita, e só então corrija

Criar chave nova é quase sempre o último passo, não o primeiro

Seu próximo movimento prático: rode /status, compare o resultado com a ordem de precedência das credenciais da Anthropic (gateway dos apps Claude, apiKeyHelper, CLAUDE_CODE_OAUTH_TOKEN, perfil em ANTHROPIC_PROFILE, OAuth do /login) e lembre que variável de provedor de nuvem setada coloca a credencial do provedor na frente na ordem de escolha

Se o 401 for de servidor MCP, é /mcp

Se for de CI, é o secret

Se for a assinatura sendo atropelada, é a variável de ambiente

Com esse mapa na cabeça, erro de autenticação deixa de ser adivinhação e vira checklist

até o próximo post!