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

Rotação e eliminação de chaves

Aula 4 de 14 Atualizada a 29 de julho de 2026 Programador
Nesta página
  1. Rotação: Renovar sem interrupções
  2. Efetuar uma rotação
  3. Eliminar uma chave
  4. Automatizar a rotação
  5. Pontos-chave

Rotação: Renovar sem interrupções

A rotação de chaves é uma prática de segurança crítica. Gera uma nova chave secreta para substituir a antiga sem eliminar a própria chave. A chave secreta antiga é imediatamente e permanentemente invalidada.

Efetuar uma rotação

A rotação resolve um problema que a eliminação não consegue: renovar o segredo sem perder a identidade da chave. As suas ACL, limites de taxa e nome sobrevivem à operação, pelo que não precisa de reconfigurar nada — apenas o segredo muda no seu cofre. Isto torna a rotação regular prática; recriar uma chave exigiria reconfigurar tudo de cada vez.

POST /auth/api-keys/{apiKeyId}/rotate
curl -X POST "https://management-api.x.ai/auth/api-keys/$API_KEY_ID/rotate" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY"

Comportamento da rotação

  • A chave secreta antiga é imediatamente invalidada — qualquer pedido que a utilize falhará com um erro 401
  • É gerada uma nova chave secreta e devolvida na resposta
  • O ID da chave (apiKeyId), o nome, as ACL e os limites de taxa permanecem inalterados
  • A nova chave secreta é apresentada apenas uma vez — guarde-a imediatamente

Processo de rotação seguro

Uma parte deste procedimento merece ênfase porque frequentemente surpreende os utilizadores: a chave secreta antiga é invalidada imediatamente. Não existe nenhum período de carência em que ambos os segredos funcionem. Quaisquer serviços que ainda utilizem o valor antigo falharão no segundo seguinte à chamada. Isto dita a ordem dos seis passos abaixo: prepare o seu cofre antes de acionar a rotação, não depois.

  1. Prepare a sua infraestrutura para aceitar uma nova chave (variável de ambiente, cofre)
  2. Efetue a rotação através da API
  3. Atualize o segredo no seu cofre imediatamente
  4. Redesloque os seus serviços com a nova chave
  5. Verifique se os pedidos têm sucesso com a nova chave
  6. Verifique a propagação através de GET /auth/api-keys/{apiKeyId}/propagation

Quando rotacionar

Três situações desencadeiam a rotação, cada uma com uma urgência diferente. Uma suspeita de fuga exige rotação imediata: um membro da equipa com acesso à chave sai, um registo contendo uma chave é exposto publicamente ou um repositório Git contém uma chave em texto simples. Nestes casos, cada hora de espera é uma hora de exposição, por isso rotacione antes de concluir a análise do incidente. A rotação baseada em políticas é preventiva: a cada 30, 60 ou 90 dias, dependendo dos seus requisitos de segurança, limita a vida útil de uma chave que possa ter sido comprometida sem ser detetada. Por fim, alterações no ambiente — migração de infraestrutura ou mudança de fornecedor — são uma oportunidade natural para começar de novo com chaves limpas, em vez de transportar chaves antigas para um contexto para o qual nunca foram desenhadas.

Eliminar uma chave

A eliminação é permanente e irrevogável. A pergunta a fazer antes de eliminar não é «Esta chave está comprometida?», mas «Ainda preciso deste âmbito de acesso?». Se a resposta for sim, precisa de uma rotação: neutraliza o segredo exposto preservando a configuração. A eliminação só se justifica para uma chave que já não é útil — um projeto parado, um fornecedor que saiu ou um ambiente desativado.

DELETE /auth/api-keys/{apiKeyId}
curl -X DELETE "https://management-api.x.ai/auth/api-keys/$API_KEY_ID" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY"

Consequências da eliminação

  • A chave e todos os seus parâmetros são permanentemente eliminados
  • Todos os pedidos que utilizem esta chave falharão imediatamente
  • A ação é irreversível — terá de criar uma nova chave com novos parâmetros
  • O histórico de utilização da chave permanece disponível nas análises

Rotação vs. eliminação

AspetoRotaçãoEliminação
A chave ainda existeSimNão
Novo segredo geradoSimNão
ACL preservadasSimNão
Limites preservadosSimNão
ReversívelNão (segredo antigo perdido)Não (chave eliminada)
Utilização típicaRenovação regularChave obsoleta ou compromisso confirmado

Automatizar a rotação

A rotação automatizada só faz sentido se a escrita no cofre fizer parte do mesmo script, sem intervenção manual no meio. Caso contrário, apenas desloca o risco: um segredo gerado por máquina e copiado à mão tem mais probabilidade de acabar na área de transferência ou no histórico do terminal do que uma chave criada a partir da consola.

import requests
import json

MANAGEMENT_API = "https://management-api.x.ai"
MGMT_KEY = "xai-mgmt-..."
KEY_ID = "key-123"

# Rotate
response = requests.post(
    f"{MANAGEMENT_API}/auth/api-keys/{KEY_ID}/rotate",
    headers={"Authorization": f"Bearer {MGMT_KEY}"}
)

new_key = response.json()
new_secret = new_key.get("secret")

# Store in your vault (example with a .env file)
# In production, use Vault, AWS Secrets Manager, etc.
print(f"New key generated. Update your vault.")

Rotação agendada

Integre a rotação no seu pipeline de CI/CD ou numa tarefa cron:

# Cron example: rotation on the 1st of each month at 3 AM
0 3 1 * * /opt/scripts/rotate-xai-keys.sh

Pontos-chave

  • POST /auth/api-keys/{apiKeyId}/rotate invalida o segredo antigo e gera um novo
  • A invalidação do segredo antigo é imediata e permanente
  • DELETE /auth/api-keys/{apiKeyId} elimina a chave irreversivelmente
  • Prefira a rotação à eliminação para manter as ACL e os limites existentes
  • Automatize a rotação com um script e um cofre de segredos
  • Verifique sempre a propagação após uma rotação