Ověření platnosti klíče pro správu
Na této stránce
Ověření integrity tvých klíčů
Ověření platnosti klíče pro správu je první obrannou linií tvé API infrastruktury. Před jakoukoli kritickou operací – nasazením, rotací klíčů nebo změnami fakturace – si ověř, že je tvůj klíč platný a má správná oprávnění.
Koncový bod pro ověření
GET /auth/management-keys/validation
curl "https://management-api.x.ai/auth/management-keys/validation" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY"
Odpověď potvrzuje, že je klíč aktivní, a vrací informace o týmu, oprávněních a souvisejících datech. Nepodceňuj datum vypršení platnosti: je to jediná informace, která ti umožní předejít výpadku místo toho, abys ho musel řešit až nastane, protože vypršený klíč tě neupozorní – při prvním následném volání jednoduše vrátí chybu 401.
Chybové případy
- 401 Unauthorized: Klíč je neplatný, vypršel nebo byl smazán
- 403 Forbidden: Klíč je platný, ale nemá potřebná oprávnění pro požadovanou operaci
Integrace do tvých skriptů
Ověření při spuštění
Ověření při spuštění přesune selhání do místa, kde stojí nejméně. Bez této kontroly se neplatný klíč projeví až při prvním smysluplném volání – tedy uprostřed zpracování, někdy až po provedení několika kroků. S touto kontrolou se skript zastaví do tří sekund s zprávou, která jasně označí příčinu.
import requests
import sys
MANAGEMENT_API = "https://management-api.x.ai"
MGMT_KEY = "xai-mgmt-..."
def validate_management_key():
"""Zkontroluje, zda je klíč pro 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("Klíč pro správu je platný")
return True
elif response.status_code == 401:
print("CHYBA: Klíč pro správu je neplatný nebo vypršel")
return False
else:
print(f"CHYBA: Neočekávaný stav {response.status_code}")
return False
except requests.exceptions.RequestException as e:
print(f"CHYBA PŘIPOJENÍ: {e}")
return False
if not validate_management_key():
sys.exit(1)
Pravidelná kontrola stavu (Healthcheck)
Pravidelná kontrola stavu pokrývá to, co ověření při spuštění nezachytí: dlouhodobě běžící služby, které byly spuštěny před týdny a jejichž klíč může během této doby vypršet nebo být zrušen. Hourly kontrola stačí – koncový bod je lehký a nespotřebovává žádné inferenční tokeny.
#!/bin/bash
# healthcheck-xai.sh — spouštět každou hodinu přes 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: Klíč pro správu xAI je neplatný (HTTP $STATUS)"
# Odeslat upozornění (PagerDuty, Slack, e-mail)
fi
Audit inferenčních klíčů
Pravidelný audit odpovídá na tři otázky, na které ti žádné upozornění samo od sebe neodpoví: které klíče stále mají zástupné znaky (wildcard), které nemají nastavené limity rychlosti a které nebyly měsíce použity. První dvě představují rizika, třetí je příležitost k úklidu – a všechny tři vyřešíš jedním průchodem.
import requests
from datetime import datetime
MANAGEMENT_API = "https://management-api.x.ai"
MGMT_KEY = "xai-mgmt-..."
TEAM_ID = "team-..."
def audit_api_keys():
"""Provede audit všech API klíčů pro 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 klíčů — {datetime.now().strftime('%d/%m/%Y %H:%M')} ===")
print(f"Celkový počet klíčů: {len(keys)}")
for key in keys:
name = key.get("name", "Nepojmenovaný")
acls = key.get("acls", [])
expire = key.get("expireTime", "Nikdy")
created = key.get("createdAt", "N/A")
# Upozornění
warnings = []
# Klíč s přístupem pomocí zástupných znaků
if "api-key:endpoint:*" in acls and "api-key:model:*" in acls:
warnings.append("PLNÝ PŘÍSTUP (zástupné znaky)")
# Klíč bez data vypršení
if expire == "Nikdy" or not expire:
warnings.append("BEZ DATA VYPRŠENÍ")
# Klíč bez limitů rychlosti
if not key.get("qps") and not key.get("qpm"):
warnings.append("BEZ LIMITŮ RYCHLOSTI")
status = " | ".join(warnings) if warnings else "OK"
print(f" [{name}] ACLs: {len(acls)} | Vyprší: {expire} | {status}")
audit_api_keys()
Kontrolní seznam bezpečnosti klíčů
Klíče pro správu
Klíče pro správu ovládají vše ostatní – jejich kompromitace umožňuje vytvářet, upravovat a mazat všechny inferenční klíče. Vyžadují proto nejpřísnější zacházení: výhradní uložení v trezoru (vault), nikdy jako plain text v kódu nebo ve verzované konfiguraci; přístup omezený pouze na administrátory infrastruktury, nikoli na vývojáře aplikací; a pravidelné ověřování pomocí GET /auth/management-keys/validation, ideálně automatizované jako healthcheck – vypršený klíč pro správu objevený v momentě, kdy ho zoufale potřebuješ, je nejhorším operačním scénářem.
Inferenční klíče (API klíče)
U inferenčních klíčů je hlavním principem izolace: každá aplikace dostane vlastní klíč, nikdy klíč sdílený mezi službami – jinak rotace kompromitovaného klíče rozbije všechny služby najednou a analytika neumožní přiřadit spotřebu ke konkrétní službě. Každý klíč nese restriktivní ACL přizpůsobené jeho skutečnému využití (žádné zástupné znaky v produkci), limity rychlosti dimenzované pro očekávaný provoz a datum vypršení, pokud je využití dočasné – POC plánovaný na dva týdny nepotřebuje věčný klíč. Pravidelný audit pomocí výše uvedeného skriptu uzavírá celý cyklus: odhalí zapomenuté, příliš privilegované nebo končící klíče dříve, než se stanou problémem.
Princip oddělení povinností
Udržuj jasné oddělení mezi klíči:
| Typ | Využití | Kdo má přístup |
|---|---|---|
| Klíč pro správu | Administrace, fakturace, analytika | Administrátoři infrastruktury |
| Produkční klíč | API volání v produkci | Produkční aplikace |
| Staging klíč | Testování před produkcí | Vývojový tým |
| Vývojový klíč | Lokální vývoj | Jednotlivý vývojář |
Každý klíč má definovaný rozsah. Pokud vývojář opustí tým, smaže se pouze jeho vývojový klíč – ostatní zůstanou nedotčeny.
Klíčové poznatky
GET /auth/management-keys/validationzkontroluje platnost tvého klíče pro správu- Integruj ověření do spuštění svých skriptů a monitoringu
- Pravidelně audituj všechny klíče, abys odhalil příliš široký přístup
- Odděluj klíče podle prostředí a odpovědnosti
- Okamžitě reaguj upozorněním na neplatný klíč (vypršel nebo byl smazán)