Key rotation

O que significa key rotation?

Key rotation, ou rotação de chaves, é trocar uma credencial de acesso por outra nova de tempos em tempos ou sempre que houver suspeita de problema. A chave antiga deixa de funcionar e passa a valer apenas a nova.

Pense na troca do segredo de um cofre: mesmo que ninguém tenha descoberto o código atual, mudá-lo regularmente diminui a chance de alguém usá-lo sem permissão. No mundo das APIs, o cofre é o acesso ao sistema e o código é a chave de API, o token ou outro segredo.

Para que serve a rotação de chaves em uma API fiscal?

Uma chave de API fiscal permite emitir, cancelar e consultar notas em nome de uma empresa. Se ela vazar, alguém poderia emitir documentos indevidos ou acessar dados sensíveis de clientes e operações.

A rotação limita o tempo em que uma chave exposta continua útil. Ela também ajuda em situações comuns do dia a dia, como a saída de um desenvolvedor da equipe, a troca de um fornecedor ou a descoberta de uma chave salva por engano em um repositório de código ou em um log.

Como funciona a rotação de uma API Key na prática?

O processo costuma seguir alguns passos: gerar uma nova chave no painel ou console do serviço, atualizar essa chave nos sistemas que fazem as chamadas (ERP, plataforma de vendas, servidores), confirmar que as requisições com a nova chave estão funcionando e, por fim, revogar a chave antiga.

Muitos serviços permitem manter duas chaves ativas ao mesmo tempo por um período curto. Essa sobreposição evita que a emissão de notas pare enquanto todos os sistemas são atualizados. Depois da troca concluída, a chave anterior deve ser desativada para que a rotação tenha efeito real.

Com que frequência as chaves devem ser trocadas?

Não existe um prazo único obrigatório. Cada empresa define sua política conforme o risco, as regras internas de segurança e as exigências de clientes ou auditorias. O importante é ter uma rotina definida, e não trocar apenas quando algo dá errado.

Além da troca programada, a rotação deve ser imediata quando houver suspeita de vazamento, quando alguém com acesso deixar a empresa ou quando uma chave aparecer em local inadequado, como e-mails, planilhas ou mensagens de chat.

Qual a diferença entre rotação de API Key e renovação do certificado digital?

A API Key identifica o sistema que está chamando a API do emissor. Já o certificado digital A1 identifica a empresa perante a SEFAZ ou a prefeitura e é usado para assinar o XML dos documentos fiscais. São credenciais diferentes, com finalidades diferentes.

O certificado digital tem prazo de validade e precisa ser renovado antes de vencer, senão a emissão é bloqueada. A rotação da API Key, por outro lado, é uma decisão de segurança da empresa. Em ambos os casos vale a mesma lógica: substituir a credencial com planejamento para não interromper a operação. Outros segredos fiscais, como o CSC da NFC-e, também podem ser substituídos seguindo esse cuidado.

Como fazer key rotation sem interromper a emissão de notas?

O primeiro passo é não deixar a chave espalhada pelo código. Guardá-la em um cofre de segredos ou em variáveis de ambiente facilita a troca, porque basta atualizar um único lugar. Ferramentas como key vault e serviços de gerenciamento de chaves ajudam a automatizar esse processo.

Também é recomendável testar a nova chave no ambiente de homologação antes de aplicá-la em produção, acompanhar os logs logo após a troca para identificar falhas de autenticação e registrar quem fez a rotação e quando, mantendo uma trilha de auditoria.

Exemplos de Key rotation

• Uma software house que integra o ERP de seus clientes a uma API fiscal define que todas as API Keys de produção são trocadas a cada seis meses, mantendo a chave antiga ativa por alguns dias até que todos os servidores estejam atualizados.
• Um desenvolvedor publica por engano uma chave de API em um repositório público. A equipe gera imediatamente uma nova chave no console do emissor, atualiza o sistema de vendas e revoga a chave exposta.
• Um marketplace que emite NFC-e e NF-e para vários lojistas armazena as chaves em um cofre de segredos, o que permite fazer a rotação sem alterar o código da aplicação.
• Uma empresa que libera um agente de inteligência artificial para consultar documentos fiscais via MCP cria uma credencial exclusiva para ele e a substitui periodicamente, revisando as permissões a cada troca.