Onde a chave de API nunca pode estar

Chave de API vazada é o incidente mais comum e o mais evitável. Quase sempre por um destes caminhos: foi para o repositório, foi para o navegador, ou ficou num arquivo de texto que alguém abriu.

Onde a chave nunca pode estar

No código versionado. Commit apagado não some: fica no histórico. Se a chave passou pelo repositório, considere-a comprometida — mesmo que o repositório seja privado, mesmo que você tenha revertido.

No navegador. Se o código que usa a chave roda no cliente, a chave está pública. Não existe ofuscação que resolva; o inspetor mostra tudo. O navegador chama o seu backend, e o seu backend chama a API.

Em arquivo de texto sem proteção. Uma pasta com .txt de credenciais não é cofre. Qualquer processo rodando com o seu usuário lê. Se a chave esteve num arquivo assim, trate como exposta.

Em mensagem, chamado ou chat. Colar chave para pedir ajuda a espalha por sistemas que você não controla e que guardam histórico.

Onde ela deve estar

Variável de ambiente para o processo em execução, injetada pela plataforma — não commitada.

Cofre de segredos quando existe equipe. Cofre de verdade tem controle de acesso e registro de quem leu.

Um detalhe que costuma escapar: variável marcada como sensível na plataforma não é mais legível depois de salva, nem pelo painel nem pela linha de comando. Isso é o certo do ponto de vista de segurança, e é uma armadilha operacional — se essa era a sua única cópia, ela não existe mais. Guarde a cópia de recuperação antes de marcar como sensível.

Uma chave por finalidade

Uma chave só para tudo tem dois problemas: você não sabe quem gastou o quê, e revogar derruba tudo de uma vez.

Prefira uma chave por aplicação e por ambiente. Quando uma vaza, você revoga só aquela, e sabe exatamente o que parou.

Rotação: o plano importa mais que a frequência

Trocar chave sem plano derruba produção. A ordem que evita isso:

1. Crie a chave nova, sem apagar a antiga.
2. Publique a nova onde a aplicação lê.
3. Confirme que o tráfego está usando a nova.
4. Só então revogue a antiga.

Inverter os passos 3 e 4 é o motivo mais comum de indisponibilidade durante rotação.

E rotação parcial não é rotação: se você troca cinco chaves e esquece a sexta, a porta continua aberta. Faça a lista antes — todo lugar que guarda credencial, incluindo integração de terceiro e ferramenta de automação.

Quando desconfiar

Trate como vazamento, sem esperar confirmação:

• consumo que não bate com o seu tráfego;
• requisição vinda de endereço que você não reconhece;
• alerta do provedor de repositório sobre segredo exposto;
• alguém saiu da equipe e tinha acesso.

Nesses casos revogue primeiro e investigue depois. Chave é barata; saldo consumido e dado acessado, não.

O que fazer se vazou

1. Revogue a chave. Antes de qualquer outra coisa.
2. Crie a nova e publique.
3. Confira o consumo desde a data provável do vazamento.
4. Descubra por onde saiu — repositório, navegador, arquivo, mensagem. Sem isso, a nova chave vai pelo mesmo caminho.
5. Feche o caminho.

Pular o passo 4 é o erro que faz o incidente se repetir em dois meses.

Um hábito que evita a maior parte disso

Um verificador de segredos no commit. É configuração de minutos e pega o caso mais comum de todos: a chave que ia para o repositório sem ninguém perceber.

Para criar, listar e revogar chaves, a área de Chaves de API fica no painel, e o formato de autenticação está na documentação.

A API de números virtuais aceita a chave no cabeçalho Authorization: Bearer ou em X-API-Key.