Como faço para rotacionar uma chave de API?

Rotacionar chaves de API regularmente é uma prática importante de segurança. Veja como rotacionar suas chaves com segurança sem interromper seu serviço.

Por que rotacionar chaves de API?

• Boa prática de segurança: Limita a exposição caso uma chave seja comprometida

• Mudanças na equipe: Quando desenvolvedores saem ou mudam de função

• Suspeita de comprometimento: Se você acredita que uma chave pode ter sido exposta

• Conformidade: Algumas políticas de segurança exigem rotação periódica de chaves

• Mudanças de ambiente: Ao migrar infraestrutura ou refatorar

Processo padrão de rotação (zero downtime)

Etapa 1: Crie uma nova chave

1. Faça login em Configurações → API

2. Clique em "Criar nova chave de API"

3. Nomeie de forma descritiva (por exemplo, "Web de Produção v2")

4. Copie a nova chave imediatamente — ela é exibida apenas uma vez

5. Armazene com segurança

Etapa 2: Atualize sua aplicação

• Implante a nova chave na sua aplicação (variáveis de ambiente, gerenciador de segredos, etc.)

• Reinicie sua aplicação para carregar a nova chave

• Verifique se a nova chave está funcionando corretamente

• Monitore para identificar quaisquer erros

Etapa 3: Monitore a transição

• Mantenha as duas chaves ativas temporariamente

• Verifique em Configurações → API as datas de "Último uso"

• Aguarde até que a chave antiga não mostre atividade recente

• Garanta que todas as instâncias/serviços tenham mudado para a nova chave

Etapa 4: Exclua a chave antiga

• Depois de confirmar que a chave antiga não está mais em uso

• Exclua ou desative a chave antiga em Configurações → API

• Registre a rotação para seus registros

Processo rápido de rotação (se comprometida)

Se uma chave estiver definitivamente comprometida e você precisar agir imediatamente:

1. Exclua primeiro a chave comprometida em Configurações → API

2. Crie uma nova chave de substituição

3. Implante rapidamente a nova chave em todas as aplicações

4. Aceite uma breve indisponibilidade para evitar acesso não autorizado

5. Monitore os logs de uso para qualquer atividade suspeita

6. Entre em contato com o suporte se necessário

Estratégia de rotação com múltiplos ambientes

Para sistemas de produção, use uma abordagem em etapas:

Semana 1: Desenvolvimento

• Crie e implante a nova chave no ambiente de desenvolvimento

• Teste minuciosamente

Semana 2: Homologação

• Implante a nova chave na homologação

• Execute testes de integração

• Monitore para identificar problemas

Semana 3: Produção

• Implante a nova chave na produção durante um período de baixo tráfego

• Monitore de perto

• Mantenha a chave antiga ativa por 24-48 horas como alternativa

Semana 4: Limpeza

• Verifique se a chave antiga não mostra atividade

• Exclua a chave antiga

• Atualize a documentação

Exemplo de automação

Script para ajudar a verificar se a rotação da chave foi concluída:

#!/bin/bash
# check-api-key.sh
OLD_KEY="sk_live_OLD123..."
NEW_KEY="sk_live_NEW789..."
echo "Testing old key..."
OLD_RESPONSE=$(curl -s -w "%{http_code}" -X POST https://api.cathopic.com/resources \
  -H "x-api-key: $OLD_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"test","page":1,"page_size":1}')
echo "Testing new key..."
NEW_RESPONSE=$(curl -s -w "%{http_code}" -X POST https://api.cathopic.com/resources \
  -H "x-api-key: $NEW_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"test","page":1,"page_size":1}')
echo "Old key status: ${OLD_RESPONSE: -3}"
echo "New key status: ${NEW_RESPONSE: -3}"
if [ "${NEW_RESPONSE: -3}" == "200" ]; then
  echo "✅ New key is working!"
else
  echo "❌ New key failed!"
fi

Boas práticas

• Rotacione regularmente: A cada 90 dias para chaves de produção

• Documente as rotações: Mantenha um registro de quando as chaves foram rotacionadas e por quê

• Teste antes de excluir: Verifique sempre se a nova chave funciona antes de remover a antiga

• Use várias chaves: Separe chaves por ambiente para facilitar a rotação

• Automatize quando possível: Use ferramentas de gerenciamento de segredos que suportem rotação automática

Checklist após a rotação

Confirme estes itens após rotacionar:

• ✅ Todas as instâncias de produção usando a nova chave

• ✅ Todos os ambientes de homologação/desenvolvimento atualizados (se estiver usando a mesma chave)

• ✅ Variáveis de ambiente atualizadas

• ✅ Segredos do CI/CD atualizados

• ✅ Documentação atualizada

• ✅ Membros da equipe notificados

• ✅ Chave antiga excluída

• ✅ Rotação registrada para fins de auditoria