Rotação e eliminação de chaves
Nesta página
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.
- Prepare a sua infraestrutura para aceitar uma nova chave (variável de ambiente, cofre)
- Efetue a rotação através da API
- Atualize o segredo no seu cofre imediatamente
- Redesloque os seus serviços com a nova chave
- Verifique se os pedidos têm sucesso com a nova chave
- 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
| Aspeto | Rotação | Eliminação |
|---|---|---|
| A chave ainda existe | Sim | Não |
| Novo segredo gerado | Sim | Não |
| ACL preservadas | Sim | Não |
| Limites preservados | Sim | Não |
| Reversível | Não (segredo antigo perdido) | Não (chave eliminada) |
| Utilização típica | Renovação regular | Chave 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}/rotateinvalida 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