Rotação de chaves e ciclo de vida
Nesta página
Por que a rotação de chaves é essencial
Uma objeção comum nas sessões de formação é: «A minha chave nunca foi comprometida, por que alterá-la?» A resposta resume-se a uma palavra: incerteza. Nunca pode provar que uma chave não foi exposta — um registo detalhado esquecido num servidor, uma captura de ecrã partilhada num ticket de suporte, uma estação de trabalho de programador comprometida há seis meses. A rotação regular transforma esta incerteza num risco delimitado: mesmo que uma chave tenha sido copiada sem o seu conhecimento, deixará de funcionar na próxima rotação. Este é exatamente o raciocínio utilizado pelos auditores SOC 2; estes esperam uma política de rotação documentada. É a isto que chamamos redução da superfície de ataque temporal: quanto mais tempo uma chave viver, maior será a janela de exploração para um comprometimento silencioso.
A API de Gestão da xAI foi concebida para tornar esta prática indolor: disponibiliza um endpoint dedicado que lhe permite rotacionar uma chave sem reescrever as suas configurações.
Rotação através da API de Gestão
O endpoint de rotação é direto:
POST https://management-api.x.ai/auth/api-keys/{apiKeyId}/rotate
Certifique-se de que compreende o que esta chamada faz antes de a utilizar: gera uma nova chave secreta para o ID existente e invalida permanentemente a antiga, mantendo as ACLs, os limites de taxa e as configurações associadas à chave. O aspeto que apanha as equipas de surpresa na primeira vez é que a alteração é imediata e irreversível. Se o seu backend de produção estiver a utilizar esta chave quando acionar a rotação, começará a receber erros de autenticação em segundos. Não há período de carência, nem forma de reverter.
É por isso que, em produção, geralmente prefere um procedimento em dois passos para evitar qualquer interrupção. Primeiro, crie uma nova chave via POST /auth/teams/{teamId}/api-keys, com exatamente as mesmas permissões da antiga. De seguida, verifique a sua propagação com GET /auth/api-keys/{newKeyId}/propagation — uma chave recém-criada não é instantaneamente conhecida em toda a infraestrutura, e uma implementação prematura produz erros confusos. Depois, implemente a nova chave nos seus backends e teste se as chamadas funcionam realmente com ela, não apenas se a implementação terminou sem erros. Só após ter esta confirmação é que deve desativar a chave antiga, ou deixá-la atingir a sua expiração, antes de a eliminar permanentemente com DELETE /auth/api-keys/{oldKeyId}.
Esta abordagem «nova chave e depois eliminar» oferece-lhe um período de sobreposição onde ambas as chaves coexistem: se a implementação falhar num servidor, nada se quebra. A rotação no local permanece disponível se quiser manter o mesmo ID de chave:
curl -X POST \
"https://management-api.x.ai/auth/api-keys/key_abc123/rotate" \
-H "Authorization: Bearer $MANAGEMENT_KEY"
Neste caso, planeie atualizar os seus backends imediatamente, uma vez que a chave antiga morre no instante em que a chamada é concluída.
O ciclo de vida completo de uma chave
Uma chave bem gerida tem uma história em quatro atos. Na criação, via POST /auth/teams/{teamId}/api-keys, define o seu nome, as suas ACLs e — este é o hábito a consolidar — a sua data de expiração:
{
"name": "prod-chat-service",
"acls": ["api-key:endpoint:chat", "api-key:model:grok-4.3"],
"expireTime": "2026-12-31T23:59:59Z"
}
Uma chave sem expireTime é uma chave que viverá para sempre se ninguém pensar nisso; uma chave com expiração obriga a sua equipa a colocar a questão da renovação numa data fixa. Segue-se a monitorização: GET /v1/api-key indica-lhe o estado da chave (api_key_blocked, api_key_disabled), e a consola da xAI expõe o uso e as anomalias. Para modificações a meio da vida — mudar o nome, ajustar ACLs, apertar limites de taxa, adiar a expiração — utilize PUT https://management-api.x.ai/auth/api-keys/{api_key_id}. Finalmente, a eliminação, DELETE /auth/api-keys/{apiKeyId}, é permanente e irreversível: qualquer aplicação que utilize esta chave deixa de funcionar instantaneamente. Antes de eliminar, assegure-se de que nenhum serviço esquecido — um cron mensal, um script de relatórios — ainda depende dela.
Que estratégia de rotação deve adotar?
A frequência certa depende da sensibilidade do seu ambiente. A rotação mensal é obrigatória em contextos altamente sensíveis, como finanças ou saúde, onde a janela de exposição deve permanecer mínima. A rotação trimestral adequa-se a ambientes profissionais padrão: frequente o suficiente para ser eficaz, espaçada o suficiente para não sobrecarregar as equipas. A rotação anual, acoplada a uma data de expiração definida, é o mínimo aceitável — abaixo disso, a sua política de rotação não é verdadeiramente uma política. Em todos os casos, a automação via um script agendado poupa-o de depender da memória de um administrador.
A rotação orientada por eventos soma-se a este calendário, sendo acionada por circunstâncias e não por datas. Acioná-la-á mais frequentemente aquando da saída de um colaborador que teve acesso a chaves: mesmo que a separação seja cordial, a chave que ele conhecia deve ser rotacionada no mesmo dia — esta é uma regra de higiene de segurança, não um sinal de desconfiança. Faça o mesmo em caso de suspeito comprometimento, um incidente de segurança na sua infraestrutura, ou uma mudança de fornecedor que teve acesso aos seus sistemas.
Vinte minutos para retomar o controlo do seu inventário
O melhor momento para descobrir o estado real das suas chaves não é no dia da auditoria. Portanto, liste agora todas as suas chaves com GET /auth/teams/{teamId}/api-keys e identifique aquelas sem expiração, para adicionar um expireTime. Para cada uma, pergunte a si mesmo se as suas ACLs correspondem ao mínimo estrito exigido pela aplicação que as utiliza; uma chave criada para um protótipo e reciclada para produção quase sempre carrega direitos em excesso.
De seguida, elimine as chaves não utilizadas, porque cada chave ativa é um vetor de ataque potencial, e uma chave de que ninguém se lembra é a pior de todas: ninguém notará o seu uso anómalo. Termine por documentar quem tem acesso a qual chave e porquê. Este documento, mais do que as próprias chaves, é o que apresentará na próxima auditoria.
Pontos-chave
- O endpoint
POST /auth/api-keys/{id}/rotateinvalida a chave antiga permanentemente, sem período de carência - Em produção, prefira criar uma nova chave e depois eliminar a antiga para evitar qualquer interrupção
- Defina sempre uma data de expiração nas suas chaves
- Automatize a rotação com um script agendado (mensal, trimestral ou anual, consoante a sensibilidade)
- Acione a rotação imediata aquando de qualquer mudança de pessoal ou incidente de segurança