Validarea cheii de management
Pe această pagină
Verificarea integrității cheilor dumneavoastră
Validarea cheii de management reprezintă prima linie de apărare a infrastructurii API. Înainte de orice operațiune critică—lansare în producție, rotație a cheilor, modificări de facturare—verificați dacă cheia este validă și dacă permisiunile sale sunt corecte.
Endpoint de validare
GET /auth/management-keys/validation
curl "https://management-api.x.ai/auth/management-keys/validation" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY"
Răspunsul confirmă că cheia este activă și returnează echipa, permisiunile și datele asociate. Nu neglijați data de expirare: aceasta este singura informație care vă permite să anticipați o întrerupere în loc să o suferiți, deoarece o cheie expirată nu vă avertizează—ea returnează pur și simplu codul 401 la prima apelare care urmează.
Cazuri de eroare
- 401 Unauthorized: Cheia este invalidă, expirată sau a fost ștearsă
- 403 Forbidden: Cheia este validă, dar nu deține permisiunile necesare pentru operațiunea solicitată
Integrarea în scripturile dumneavoastră
Verificare la pornire
Validarea la pornire mută eșecul acolo unde costă cel mai puțin. Fără această verificare, o cheie invalidă se manifestă la primul apel util—adică în mijlocul procesării, uneori după ce mai mulți pași au fost deja executați. Cu ea, scriptul se oprește în trei secunde cu un mesaj care indică cauza.
import requests
import sys
MANAGEMENT_API = "https://management-api.x.ai"
MGMT_KEY = "xai-mgmt-..."
def validate_management_key():
"""Checks that the management key is valid."""
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("Management key valid")
return True
elif response.status_code == 401:
print("ERROR: Management key invalid or expired")
return False
else:
print(f"ERROR: Unexpected status {response.status_code}")
return False
except requests.exceptions.RequestException as e:
print(f"CONNECTION ERROR: {e}")
return False
if not validate_management_key():
sys.exit(1)
Verificare periodică a stării (Healthcheck)
Verificarea periodică a stării acoperă ceea ce validarea la pornire ratează: servicii cu durată lungă de funcționare, pornite acum câteva săptămâni, a căror cheie poate expira sau poate fi revocată pe parcurs. O verificare orară este suficientă—endpoint-ul este ușor și nu consumă tokeni de inferență.
#!/bin/bash
# healthcheck-xai.sh — run every hour 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 "ALERT: xAI management key invalid (HTTP $STATUS)"
# Send an alert (PagerDuty, Slack, email)
fi
Auditarea cheilor de inferență
Auditarea periodică răspunde la trei întrebări pe care nicio alertă nu vi le va pune: care chei mai conțin caractere joker (wildcard), care nu au limite de rată și care nu au fost folosite de luni de zile. Primele două reprezintă riscuri, iar a treia este o oportunitate de curățare—și toate trei sunt gestionate într-o singură trecere.
import requests
from datetime import datetime
MANAGEMENT_API = "https://management-api.x.ai"
MGMT_KEY = "xai-mgmt-..."
TEAM_ID = "team-..."
def audit_api_keys():
"""Audits all API keys for the team."""
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"=== API Key Audit — {datetime.now().strftime('%d/%m/%Y %H:%M')} ===")
print(f"Total number of keys: {len(keys)}")
for key in keys:
name = key.get("name", "Unnamed")
acls = key.get("acls", [])
expire = key.get("expireTime", "Never")
created = key.get("createdAt", "N/A")
# Alerts
warnings = []
# Key with wildcard access
if "api-key:endpoint:*" in acls and "api-key:model:*" in acls:
warnings.append("TOTAL ACCESS (wildcards)")
# Key without expiration
if expire == "Never" or not expire:
warnings.append("NO EXPIRATION")
# Key without rate limits
if not key.get("qps") and not key.get("qpm"):
warnings.append("NO RATE LIMITS")
status = " | ".join(warnings) if warnings else "OK"
print(f" [{name}] ACLs: {len(acls)} | Expire: {expire} | {status}")
audit_api_keys()
Lista de verificare a securității cheilor
Chei de management
Cheile de management controlează totul restul—compromiterea lor acordă acces pentru a crea, modifica și șterge toate cheile de inferență. Prin urmare, ele necesită cea mai strictă manipulare: stocare exclusivă într-un seif (vault), niciodată în text clar în cod sau în configurații versionate; acces limitat doar administratorilor de infrastructură, nu și dezvoltatorilor de aplicații; și validare regulată prin GET /auth/management-keys/validation, ideal automatizată ca verificare de stare—descoperirea unei chei de management expirate chiar când aveți nevoie urgentă de ea reprezintă cel mai grav scenariu operațional.
Chei de inferență (chei API)
Pentru cheile de inferență, principiul director este izolarea: fiecare aplicație primește propria sa cheie, niciodată o cheie partajată între servicii—altfel, rotirea unei chei compromise întrerupe toate serviciile simultan, iar analitica nu mai permite atribuirea consumului. Fiecare cheie poartă liste ACL restrictive, calibrate la utilizarea sa reală (fără caractere joker în producție), limite de rată dimensionate pentru traficul estimat și o dată de expirare când utilizarea este temporară—un POC menit să dureze două săptămâni nu are nevoie de o cheie eternă. Auditarea regulată prin scriptul de mai sus închide bucla: aceasta dezvăluie cheile uitate, cu privilegii excesive sau care expiră înainte ca acestea să devină probleme.
Principiul separării sarcinilor
Mențineți o separare clară între chei:
| Tip | Utilizare | Cine are acces |
|---|---|---|
| Cheie de management | Administrare, facturare, analitică | Administratori de infrastructură |
| Cheie de producție | Apeluri API în producție | Aplicația de producție |
| Cheie de staging | Testare pre-producție | Echipa de dezvoltare |
| Cheie de dezvoltare | Dezvoltare locală | Dezvoltator individual |
Fiecare cheie are un scop definit. Dacă un dezvoltator părăsește echipa, doar cheia sa de dezvoltare este ștearsă—celelalte rămân intacte.
Puncte cheie
GET /auth/management-keys/validationverifică validitatea cheii dumneavoastră de management- Integrați validarea în pornirea scripturilor și în monitorizare
- Auditați regulat toate cheile pentru a detecta accesul prea larg
- Separați cheile în funcție de mediu și responsabilitate
- Generați alerte imediat la detectarea unei chei invalide (expirată sau ștearsă)