O que é a Claude API key, para que ela serve e como guardá-la sem vazar

Vou começar pela parte chata: a Claude API key é a senha do seu projeto, não um detalhe de configuração

Ela é a credencial que autentica cada requisição que sai do seu código para a API da Anthropic

O Console mostra a chave completa uma única vez, no momento da criação, e depois não tem como visualizar de novo, só criar outra

E o ponto que costuma doer: quem estiver com a sua chave em mãos consegue usar a API e o gasto cai no SEU billing

Aqui a ideia é entender o que é essa chave, em quais lugares ela entra e, principalmente, como guardar sem vazar 🙂

Para que serve a chave na prática: onde ela entra

A chave aparece em três contextos bem diferentes, e confundir esses contextos é onde mora boa parte dos vazamentos

Se você conhece token de API de qualquer outro serviço, o conceito é o mesmo: um segredo que prova pro servidor que a requisição é sua

Formação Recomendada

Formação Claude Code

Domine Claude Code do absoluto zero até o avançado

• 116 aulas
• 4 projetos
• 9h 23min

Conhecer formação

Em chamada HTTP direta: o cabeçalho x-api-key

Quando você bate na API na mão, sem SDK, a chave vai em um cabeçalho

E atenção nesse detalhe, porque é o erro mais comum de quem vem de outras APIs: o header não é Authorization

x-api-key: SUA_CHAVE
anthropic-version: 2023-06-01

Os dois andam juntos: o x-api-key autentica e o anthropic-version diz qual versão da API você está falando

Nos SDKs oficiais: a variável de ambiente ANTHROPIC_API_KEY

Aqui tem uma facilidade que muita gente ignora e acaba escrevendo a chave no meio do código sem precisar

Os client SDKs oficiais leem a chave AUTOMATICAMENTE da variável de ambiente ANTHROPIC_API_KEY

Ou seja: você exporta a variável no ambiente e o SDK se vira sozinho

export ANTHROPIC_API_KEY="sk-ant-..."

Sim, as chaves da API do Claude começam com o prefixo sk-ant-

Isso é útil de saber por um motivo prático: dá pra procurar esse prefixo no seu próprio projeto e ver se ele está aparecendo onde não devia 👀

No Claude Code: a variável tem precedência sobre a assinatura

Esse aqui pega gente experiente de surpresa

No Claude Code, se a variável ANTHROPIC_API_KEY estiver definida, ela tem precedência sobre a assinatura autenticada

Na prática: mesmo logado com assinatura, o consumo passa a ser cobrado nas tarifas pay-as-you-go da API

Pra usar a assinatura, a variável precisa ficar sem valor

Não é bug, é ordem de prioridade, e vale decidir isso de propósito e não por acidente

Como guardar a Claude API key sem vazar

A recomendação oficial da Anthropic é direta: guardar em um gerenciador de segredos, rotacionar periodicamente e revogar qualquer chave que você suspeite ter vazado

Bora destrinchar isso em passos, com o erro clássico de cada um

1. Chave em variável de ambiente, nunca escrita no código

A Anthropic recomenda injetar a chave por variável de ambiente justamente pra ela não morar no código

O erro comum deste passo: colar a chave direto numa constante "só pra testar rapidinho" e depois esquecer que ela ficou lá

Aquele teste rápido é exatamente o que vai pro commit

2. Usando dotenv, coloque o .env no .gitignore ANTES do primeiro commit

Se você guarda segredos localmente com dotenv, os arquivos .env precisam entrar no arquivo de ignore do controle de versão pra não serem distribuídos publicamente

# .gitignore
.env
.env.local

O erro comum deste passo: adicionar o .gitignore DEPOIS que o .env já foi versionado

Tome cuidado aqui, porque parar de rastrear o arquivo agora não apaga o que já está no histórico do repositório

Se a chave já entrou no histórico, ela deve ser tratada como vazada, ponto

3. Em produção, use a solução de segredos do provedor de nuvem

A orientação é variável de ambiente no desenvolvimento e, na nuvem, a solução de gerenciamento de segredos do próprio provedor

Junto com isso vem a rotação periódica: chave antiga demais é chave que você não sabe mais quem tocou

O erro comum deste passo: tratar "funciona no meu ambiente local" como estratégia de produção e subir a chave num arquivo de configuração do deploy

4. Escolha a expiração no momento da criação

A chave é criada no Console, em Settings > API keys, onde você dá um nome, escolhe o workspace ao qual ela fica limitada e define uma expiração

As opções incluem presets de 3 horas, 1 dia, 7 dias, 30 dias, duração personalizada ou Never

O erro comum deste passo: marcar Never no automático em uma chave que era só pra um teste de tarde

E se liga nisso: a expiração é definida só na criação e não pode ser alterada depois

Escolheu errado? Só criando outra chave

5. Aproveite o escopo de workspace e os limites do Console

Cada chave é limitada (scoped) a um único workspace, e o Console permite definir limites de gasto e de rate limit por workspace

Isso é o seu guardrail (limite) de estrago: se uma chave vazar, ela vaza dentro de um workspace com teto, não na sua conta inteira

O erro comum deste passo: usar uma única chave eterna pra tudo, do script pessoal ao serviço em produção

Quando ela cair, cai tudo junto

Chave exposta: o que acontece e o que fazer

Agora a parte que ninguém quer viver, mas todo mundo precisa saber antes

Sintoma 1: a chave foi commitada em repositório público

Causa: segredo versionado, aquele clássico de .env sem ignore ou chave hardcoded

O que acontece: a Anthropic é parceira do programa de secret scanning do GitHub

Se uma chave da API é detectada em repositório público, o GitHub notifica a Anthropic, a chave exposta é desativada automaticamente e você recebe um e-mail de aviso

E em repositório privado? Clientes do GitHub Advanced Security também podem escanear e bloquear tokens da Anthropic

Essa rede de proteção é ótima, mas não é plano de segurança: ela existe pra reduzir o dano, não pra você contar com ela

Sintoma 2: a chave está sendo usada direto no navegador

Causa: chamada client-side, com o front conversando direto com a API

O SDK lança erro por padrão quando roda em ambiente de navegador, exatamente pra evitar expor a credencial

Só roda no browser se o dev ligar explicitamente a opção dangerouslyAllowBrowser, junto com o header anthropic-dangerous-direct-browser-access do lado da API

E por que o nome tem "dangerous"? Porque em chamada direta do navegador qualquer pessoa com o devtools aberto consegue ler a chave na requisição

É literalmente entregar a senha do projeto pra quem apertar F12

Esse cuidado vale pra qualquer serviço em que você conecta um modelo por chave de API, não só pro Claude

A solução nos dois casos é a mesma

Revogar a chave comprometida

Criar uma chave nova (lembrando que a nova aparece por inteiro só uma vez)

E mover a chamada pro servidor, deixando o front conversar com o SEU backend e o backend com a API

API key, Admin API key e assinatura do Claude: o que é o quê

Tem três coisas com nome parecido que vivem sendo confundidas

A tabela separa cada uma:

A linha de baixo é a que mais gera confusão no suporte

Assinatura paga do Claude e uso da API são produtos e cobranças separados: o uso da API é cobrado à parte

A implicação prática pra quem quer os dois: assinar o plano no claude.ai e configurar o billing do Console separadamente

Se você ainda está decidindo por qual caminho ir, vale olhar a diferença entre usar o Claude no chat ou pela API antes de gerar chave pra qualquer coisa

Resumindo: chave é credencial, não configuração

A regra é uma só e cabe em uma linha: variável de ambiente, fora do repositório, fora do front

O resto é consequência disso

Próximos passos que dá pra fazer hoje:

• Abrir o projeto e conferir se existe .env versionado ou chave sk-ant- escrita no código
• Na próxima chave criada, definir expiração de propósito (ela é imutável depois) e usar o escopo de workspace com limite de gasto
• No Claude Code, decidir conscientemente se ANTHROPIC_API_KEY fica definida (cobra na API) ou sem valor (usa a assinatura)

E se bateu a dúvida de "será que essa chave já vazou?", trate como se tivesse vazado e revogue

Criar chave nova custa dois minutos, descobrir gasto estranho no billing custa bem mais 😅

até o próximo post!