Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Rotação de chaves e ciclo de vida

Aula 7 de 12 Atualizada a 28 de julho de 2026 Avancado
Nesta página
  1. Por que a rotação de chaves é essencial
  2. Rotação através da API de Gestão
  3. O ciclo de vida completo de uma chave
  4. Que estratégia de rotação deve adotar?
  5. Vinte minutos para retomar o controlo do seu inventário
  6. Pontos-chave

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}/rotate invalida 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