Validar a Chave de Gestão
Nesta página
Verificar a integridade das suas chaves
A validação da chave de gestão é a primeira linha de defesa da sua infraestrutura de API. Antes de qualquer operação crítica — implementação, rotação, alterações de faturação — verifique se a sua chave é válida e se as suas permissões estão corretas.
Endpoint de validação
GET /auth/management-keys/validation
curl "https://management-api.x.ai/auth/management-keys/validation" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY"
A resposta confirma que a chave está ativa e devolve a equipa, as permissões e as datas associadas. Não negligencie a data de expiração: esta é a única informação que lhe permite antecipar uma interrupção em vez de a sofrer, uma vez que uma chave expirada não o avisa — simplesmente devolve um erro 401 na primeira chamada subsequente.
Casos de erro
- 401 Unauthorized: A chave é inválida, expirou ou foi eliminada
- 403 Forbidden: A chave é válida, mas não possui as permissões necessárias para a operação solicitada
Integrar nos seus scripts
Verificação no arranque
Validar no arranque desloca a falha para onde ela custa menos. Sem esta verificação, uma chave inválida manifesta-se na primeira chamada útil — ou seja, no meio do processamento, por vezes após vários passos já terem sido executados. Com ela, o script para em três segundos com uma mensagem que identifica a causa.
import requests
import sys
MANAGEMENT_API = "https://management-api.x.ai"
MGMT_KEY = "xai-mgmt-..."
def validate_management_key():
"""Verifica se a chave de gestão é válida."""
try:
response = requests.get(
f"{MANAGEMENT_API}/auth/management-keys/validation",
headers={"Authorization": f"Bearer {MGMT_KEY}"},
timeout=10
)
if response.status_code == 200:
print("Chave de gestão válida")
return True
elif response.status_code == 401:
print("ERRO: Chave de gestão inválida ou expirada")
return False
else:
print(f"ERRO: Estado inesperado {response.status_code}")
return False
except requests.exceptions.RequestException as e:
print(f"ERRO DE LIGAÇÃO: {e}")
return False
if not validate_management_key():
sys.exit(1)
Verificação periódica de saúde
A verificação periódica de saúde cobre o que a validação no arranque não deteta: serviços de longa duração, iniciados há semanas, cuja chave pode expirar ou ser revogada entretanto. Uma verificação horária é suficiente — o endpoint é leve e não consome tokens de inferência.
#!/bin/bash
# healthcheck-xai.sh — executar a cada hora via cron
STATUS=$(curl -s -o /dev/null -w "%{http_code}" \
"https://management-api.x.ai/auth/management-keys/validation" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY")
if [ "$STATUS" != "200" ]; then
echo "ALERTA: Chave de gestão xAI inválida (HTTP $STATUS)"
# Enviar um alerta (PagerDuty, Slack, email)
fi
Auditoria das chaves de inferência
A auditoria periódica responde a três perguntas que nenhum alerta fará por si: quais as chaves que ainda possuem um wildcard, quais não têm limites de taxa e quais não foram utilizadas há meses. As duas primeiras constituem riscos; a terceira é uma oportunidade de limpeza — e todas três são tratadas numa única passagem.
import requests
from datetime import datetime
MANAGEMENT_API = "https://management-api.x.ai"
MGMT_KEY = "xai-mgmt-..."
TEAM_ID = "team-..."
def audit_api_keys():
"""Audita todas as chaves de API da equipa."""
response = requests.get(
f"{MANAGEMENT_API}/auth/teams/{TEAM_ID}/api-keys",
headers={"Authorization": f"Bearer {MGMT_KEY}"}
)
keys = response.json().get("apiKeys", [])
print(f"=== Auditoria de Chaves de API — {datetime.now().strftime('%d/%m/%Y %H:%M')} ===")
print(f"Número total de chaves: {len(keys)}")
for key in keys:
name = key.get("name", "Sem nome")
acls = key.get("acls", [])
expire = key.get("expireTime", "Nunca")
created = key.get("createdAt", "N/A")
# Alertas
warnings = []
# Chave com acesso wildcard
if "api-key:endpoint:*" in acls and "api-key:model:*" in acls:
warnings.append("ACESSO TOTAL (wildcards)")
# Chave sem expiração
if expire == "Nunca" or not expire:
warnings.append("SEM EXPIRAÇÃO")
# Chave sem limites de taxa
if not key.get("qps") and not key.get("qpm"):
warnings.append("SEM LIMITES DE TAXA")
status = " | ".join(warnings) if warnings else "OK"
print(f" [{name}] ACLs: {len(acls)} | Expira: {expire} | {status}")
audit_api_keys()
Lista de verificação de segurança das chaves
Chaves de gestão
As chaves de gestão controlam tudo o resto — o seu comprometimento concede acesso para criar, modificar e eliminar todas as chaves de inferência. Exigem, portanto, o manuseamento mais rigoroso: armazenamento exclusivo num cofre, nunca em texto simples no código ou em configuração versionada; acesso limitado apenas aos administradores de infraestrutura, não aos programadores de aplicações; e validação regular via GET /auth/management-keys/validation, idealmente automatizada como uma verificação de saúde — descobrir uma chave de gestão expirada quando dela precisa urgentemente é o pior cenário operacional.
Chaves de inferência (chaves de API)
Para as chaves de inferência, o princípio orientador é o isolamento: cada aplicação recebe a sua própria chave, nunca uma chave partilhada entre serviços — caso contrário, a rotação de uma chave comprometida quebra todos os serviços de uma vez, e as análises deixam de permitir atribuir o consumo. Cada chave transporta ACLs restritivas calibradas para o seu uso real (sem wildcards em produção), limites de taxa dimensionados para o tráfego esperado e uma data de expiração quando o uso é temporário — um POC destinado a durar duas semanas não precisa de uma chave eterna. A auditoria regular através do script acima fecha o ciclo: revela chaves esquecidas, com privilégios excessivos ou prestes a expirar antes que se tornem problemas.
Princípio da separação de funções
Mantenha uma separação clara entre as chaves:
| Tipo | Utilização | Quem tem acesso |
|---|---|---|
| Chave de gestão | Administração, faturação, análises | Administradores de infraestrutura |
| Chave de produção | Chamadas de API em produção | Aplicação de produção |
| Chave de staging | Testes de pré-produção | Equipa de desenvolvimento |
| Chave de desenvolvimento | Desenvolvimento local | Programador individual |
Cada chave tem um âmbito definido. Se um programador deixar a equipa, apenas a sua chave de desenvolvimento é eliminada — as outras permanecem intactas.
Pontos-chave
GET /auth/management-keys/validationverifica a validade da sua chave de gestão- Integre a validação no arranque do seu script e na monitorização
- Audite regularmente todas as chaves para detetar acessos excessivamente amplos
- Separe as chaves por ambiente e responsabilidade
- Emita um alerta imediato perante uma chave inválida (expirada ou eliminada)