Rotacionar chave de API sem downtime

Revogar antes de trocar derruba a integração. A ordem que mantém duas chaves válidas por alguns minutos, o passo que todo mundo pula, e quando inverter tudo porque houve vazamento.

Chave de API vaza de formas banais: um console.log que subiu para o repositório, um print colado num chamado, um ex-integrante que ainda tem o .env antigo. Quando acontece, a pergunta não é se você vai trocar — é se dá para trocar sem derrubar a integração.

Dá, se você projetar para isso antes de precisar.

Por que a troca ingênua causa queda

O caminho óbvio é: revogar a chave antiga, criar uma nova, atualizar a variável de ambiente. Entre o primeiro e o terceiro passo existe uma janela em que nenhuma chave válida está em uso, e toda requisição volta 401.

Se o deploy demora dois minutos, são dois minutos de integração parada. Se algo der errado no meio, é mais.

A ordem que não derruba nada

A chave é permitir duas chaves válidas ao mesmo tempo, mesmo que por poucos minutos:

Crie a chave nova. A antiga continua funcionando.
Atualize a variável de ambiente com a nova.
Faça o deploy e espere ele concluir de verdade.
Confirme que a nova está em uso — o painel mostra o último uso de cada chave.
Só então revogue a antiga.

Zero downtime, e com ponto de recuo: se o passo 3 falhar, a antiga ainda está lá.

O passo 4 é o que quase todo mundo pula, e é o único que prova que você não vai revogar a chave que ainda está sendo usada por uma instância antiga que não reiniciou.

Quando é vazamento, a ordem muda

Se a chave foi exposta publicamente, a conta é outra: cada minuto com a chave válida é um minuto em que alguém pode gastar seu saldo.

Aí revogue primeiro e aceite a queda. Integração parada por três minutos é melhor que saldo consumido por terceiro. Chave em repositório público é achada por varredura automática em minutos, não em dias.

Como saber que uma chave vazou

Sinais que valem alerta:

Uso fora do horário do seu processo. Se sua integração roda em janela conhecida, requisição às três da manhã é sinal.
Origem inesperada. Se você chama de um servidor só, requisição de outro lugar merece explicação.
Consumo que não bate com o volume. Saldo caindo mais rápido que o número de operações que você registrou.

Esse último só existe se você registra o que a sua integração faz. Sem contabilidade própria, você não tem com o que comparar.

Uma chave por uso

O erro estrutural é ter uma chave só para tudo. Quando ela vaza, você é obrigado a trocar em todos os lugares de uma vez.

Separe por consumidor: uma para produção, uma para o pipeline de testes, uma para cada serviço que integra. Vazou a do CI? Revoga aquela, e produção nem percebe. O custo é gerenciar mais chaves; o benefício é que o raio da explosão fica pequeno.

Vale o mesmo para pessoas: chave individual para quem precisa testar manualmente. Quando alguém sai do time, você revoga a dela sem reunião.

O que fazer hoje, mesmo sem vazamento

Rotacione uma vez, de propósito. O procedimento acima, num dia calmo. Você descobre onde a chave está fincada — talvez ela esteja num lugar que ninguém lembrava, e é melhor descobrir agora.

Confira se ela está mesmo fora do repositório. git log -S procura no histórico, não só nos arquivos atuais:

git log -S "ak_live" --oneline

Se aparecer algo, a chave está no histórico do repositório — e apagar o arquivo depois não a removeu de lá. Nesse caso ela precisa ser considerada comprometida e revogada, independentemente do repositório ser privado. O básico de guardar chave fora do código começa aqui.

Escreva o procedimento. Cinco linhas num arquivo do repositório. No dia em que precisar, ninguém vai improvisar ordem de operação com a chave já exposta.

Na AltiviaCloud dá para manter mais de uma chave ativa ao mesmo tempo, que é o que essa ordem exige — e a cobrança é por pedido, não por chave, como está em preços.