Overovanie platnosti kľúča na správu
Na tejto strane
Overenie integrity tvojich kľúčov
Validácia kľúča na správu je prvou líniou obrany tvojej API infraštruktúry. Pred akoukoľvek kritickou operáciou – nasadením, rotáciou, zmenami vo fakturácii – si over, či je tvoj kľúč platný a či má správne oprávnenia.
Koncový bod pre validáciu
GET /auth/management-keys/validation
curl "https://management-api.x.ai/auth/management-keys/validation" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY"
Odpoveď potvrdzuje, že kľúč je aktívny, a vracia tím, oprávnenia a súvisiace dátumy. Neprehliadni dátum vypršania platnosti: je to jediná informácia, ktorá ti umožní predvídať výpadok namiesto toho, aby si ho len utrpel, pretože vypršaný kľúč ťa neupozorní – pri prvom nasledujúcom volaní jednoducho vráti chybu 401.
Prípady chýb
- 401 Unauthorized: Kľúč je neplatný, vypršal alebo bol odstránený
- 403 Forbidden: Kľúč je platný, ale nemá potrebné oprávnenia pre požadovanú operáciu
Integrácia do tvojich skriptov
Overovanie pri štarte
Validácia pri štarte presúva zlyhanie tam, kde stojí najmenej. Bez tejto kontroly sa neplatný kľúč prejaví až pri prvom užitočnom volaní – teda uprostred spracovania, niekedy až po vykonaní niekoľkých krokov. S ňou sa skript zastaví do troch sekúnd so správou, ktorá jasne pomenúva príčinu.
import requests
import sys
MANAGEMENT_API = "https://management-api.x.ai"
MGMT_KEY = "xai-mgmt-..."
def validate_management_key():
"""Skontroluje, či je kľúč na správu platný."""
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("Kľúč na správu je platný")
return True
elif response.status_code == 401:
print("CHYBA: Kľúč na správu je neplatný alebo vypršal")
return False
else:
print(f"CHYBA: Neočakávaný stav {response.status_code}")
return False
except requests.exceptions.RequestException as e:
print(f"CHYBA SPOJENIA: {e}")
return False
if not validate_management_key():
sys.exit(1)
Pravidelná kontrola stavu (Healthcheck)
Pravidelná kontrola stavu pokrýva to, čo validácia pri štarte vynecháva: dlho bežiace služby, spustené pred týždňami, ktorých kľúč môže počas behu vypršať alebo byť zrušený. Hourly kontrola stačí – koncový bod je ľahký a nespotrebúva žiadne tokeny na inferenciu.
#!/bin/bash
# healthcheck-xai.sh — spustiť každú hodinu cez 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)"
# Odoslať upozornenie (PagerDuty, Slack, e-mail)
fi
Auditovanie kľúčov na inferenciu
Pravidelný audit odpovedá na tri otázky, na ktoré ťa žiadny alert sám od seba neupozorní: ktoré kľúče stále obsahujú wildcard, ktoré nemajú nastavené limity rýchlosti a ktoré sa mesiace nepoužili. Prvé dve predstavujú riziko, tretia je príležitosťou na upratanie – a všetky tri vybavíš v jednom prechode.
import requests
from datetime import datetime
MANAGEMENT_API = "https://management-api.x.ai"
MGMT_KEY = "xai-mgmt-..."
TEAM_ID = "team-..."
def audit_api_keys():
"""Audituje všetky API kľúče pre tím."""
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"=== Audit API kľúčov — {datetime.now().strftime('%d/%m/%Y %H:%M')} ===")
print(f"Celkový počet kľúčov: {len(keys)}")
for key in keys:
name = key.get("name", "Nepomenovaný")
acls = key.get("acls", [])
expire = key.get("expireTime", "Nikdy")
created = key.get("createdAt", "N/A")
# Upozornenia
warnings = []
# Kľúč s prístupom cez wildcard
if "api-key:endpoint:*" in acls and "api-key:model:*" in acls:
warnings.append("ÚPLNÝ PRÍSTUP (wildcards)")
# Kľúč bez dátumu vypršania
if expire == "Nikdy" or not expire:
warnings.append("BEZ EXPIRÁCIE")
# Kľúč bez limitov rýchlosti
if not key.get("qps") and not key.get("qpm"):
warnings.append("BEZ LIMITOV RÝCHLOSTI")
status = " | ".join(warnings) if warnings else "OK"
print(f" [{name}] ACLs: {len(acls)} | Expirácia: {expire} | {status}")
audit_api_keys()
Kontrolný zoznam bezpečnosti kľúčov
Kľúče na správu
Kľúče na správu ovládajú všetko ostatné – ich kompromitácia udeľuje prístup na vytváranie, úpravu a odstraňovanie všetkých kľúčov na inferenciu. Preto si vyžadujú najprísnejšie zaobchádzanie: výlučné uloženie v trezore (vault), nikdy nie ako plain text v kóde alebo verzionovanej konfigurácii; prístup obmedzený len na administrátorov infraštruktúry, nie na vývojárov aplikácií; a pravidelnú validáciu cez GET /auth/management-keys/validation, ideálne automatizovanú ako healthcheck – vypršaný kľúč na správu objavený v momente, keď ho zúfalo potrebuješ, je najhorším operačným scenárom.
Kľúče na inferenciu (API kľúče)
Pre kľúče na inferenciu je vedúcim princípom izolácia: každá aplikácia dostane vlastný kľúč, nikdy nie kľúč zdieľaný medzi službami – inak rotácia kompromitovaného kľúča naraz rozbije všetky služby a analytika už nedokáže pripísať spotrebu. Každý kľúč nesie reštriktívne ACL prispôsobené jeho skutočnému využitiu (žiadne wildcards v produkcii), limity rýchlosti dimenzované pre očakávanú prevádzku a dátum vypršania, ak je použitie dočasné – POC určený na dva týždne nepotrebuje večný kľúč. Pravidelný audit pomocou vyššie uvedeného skriptu uzatvára kruh: odhalí zabudnuté, príliš oprávnené alebo expirujúce kľúče skôr, než sa stanú problémom.
Princíp oddelenia povinností
Udržiavaj jasné oddelenie medzi kľúčmi:
| Typ | Použitie | Kto má prístup |
|---|---|---|
| Kľúč na správu | Administrácia, fakturácia, analytika | Administrátori infraštruktúry |
| Prod kľúč | API volania v produkcii | Produkčná aplikácia |
| Staging kľúč | Testovanie pred produkciou | Vývojársky tím |
| Dev kľúč | Lokálny vývoj | Jednotlivý vývojár |
Každý kľúč má definovaný rozsah. Ak vývojár opustí tím, odstráni sa len jeho dev kľúč – ostatné zostanú nedotknuté.
Kľúčové poznatky
GET /auth/management-keys/validationskontroluje platnosť tvojho kľúča na správu- Integruj validáciu do spúšťania svojich skriptov a monitoringu
- Pravidelne audituj všetky kľúče, aby si odhalil príliš široký prístup
- Oddeľuj kľúče podľa prostredia a zodpovednosti
- Okamžite upozorni na neplatný kľúč (vypršaný alebo odstránený)