Preverjanje veljavnosti upravljalnega ključa
Na tej strani
Preveri celovitost svojih ključev
Preverjanje veljavnosti upravljalnega ključa je prva obrambna linija tvoje API infrastrukture. Pred vsako kritično operacijo – namestitvijo, zamenjavo ključa ali spremembami obračunavanja – preveri, ali je tvoj ključ veljaven in ali ima pravilna dovoljenja.
Končna točka za preverjanje
GET /auth/management-keys/validation
curl "https://management-api.x.ai/auth/management-keys/validation" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY"
Odgovor potrdi, da je ključ aktiven, in vrne podatke o ekipi, dovoljenjih ter povezanih datumih. Ne spreglej datuma poteka: to je edina informacija, ki ti omogoča, da predvidiš izpad, namesto da bi ga utrpel, saj potekel ključ ne opozori – ob prvem naslednjem klicu preprosto vrne napako 401.
Primeri napak
- 401 Unauthorized: Ključ je neveljaven, potekel ali izbrisan.
- 403 Forbidden: Ključ je veljaven, vendar nima potrebnih dovoljenj za zahtevano operacijo.
Vključevanje v tvoje skripte
Preverjanje ob zagonu
Preverjanje ob zagonu prestavi morebitno napako na trenutek, ko so stroški najmanjši. Brez tega preverjanja se neveljaven ključ pokaže šele ob prvem uporabnem klicu – torej sredi obdelave, včasih potem, ko je bilo že opravljenih več korakov. S preverjanjem se skripta ustavi v treh sekundah z sporočilom, ki jasno navaja vzrok.
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)
Periodični zdravstveni pregled
Periodični zdravstveni pregled zajame tisto, kar preverjanje ob zagonu spusti: dolgotrajne storitve, zagnane pred tedni, katerih ključ lahko med delovanjem poteče ali pa je preklican. Urno preverjanje zadostuje – končna točka je lahka in ne porablja žetonov za sklepanje (inference tokens).
#!/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
Revizija ključev za sklepanje
Periodična revizija odgovori na tri vprašanja, za katera te nobeno opozorilo ne bo vprašalo: kateri ključi še vedno nosijo nadomestni znak (wildcard), kateri nimajo omejitev hitrosti in kateri niso bili uporabljeni mesece. Prvi dve predstavljata tveganje, tretje pa priložnost za čiščenje – vse tri pa lahko obravnavaš v enem prehodu.
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()
Kontrolni seznam za varnost ključev
Upravljalni ključi
Upravljalni ključi nadzorujejo vse ostalo – njihova ogroženost omogoča dostop do ustvarjanja, spreminjanja in brisanja vseh ključev za sklepanje. Zato zahtevajo najstrožje ravnanje: izključno shranjevanje v trezorju (vault), nikoli kot golo besedilo v kodi ali različno nadzorovani konfiguraciji; dostop omejen izključno na skrbnike infrastrukture, ne pa tudi na razvijalce aplikacij; in redno preverjanje veljavnosti prek GET /auth/management-keys/validation, idealno avtomatizirano kot zdravstveni pregled – odkritje poteklega upravljalnega ključa v trenutku, ko ga nujno potrebuješ, je najslabši operativni scenarij.
Ključi za sklepanje (API ključi)
Za ključe za sklepanje je vodilno načelo izolacija: vsaka aplikacija prejme svoj ključ, nikoli ključa, ki bi ga delile več storitev – v nasprotnem primeru zamenjava ogroženega ključa hkrati poruši vse storitve, analitika pa ne omogoča več pripisovanja porabe. Vsak ključ nosi omejevalne sezname nadzora dostopa (ACL), prilagojene njegovi dejanski uporabi (v proizvodnem okolju brez nadomestnih znakov), omejitve hitrosti, prilagojene pričakovanemu prometu, in datum poteka, če je uporaba začasna – dokazni koncept (POC), namenjen dvotedenski uporabi, ne potrebuje večne ključa. Redna revizija s pomočjo zgornje skripte zaključi krog: razkrije pozabljene, preveč pooblaščene ali ključe, ki jim bo kmalu potekla veljavnost, preden postanejo težava.
Načelo ločitve dolžnosti
Ohrani jasno ločitev med ključi:
| Vrsta | Uporaba | Kdo ima dostop |
|---|---|---|
| Upravljalni ključ | Administracija, obračunavanje, analitika | Skrbniki infrastrukture |
| Proizvodni ključ | API klici v proizvodnem okolju | Proizvodna aplikacija |
| Testni ključ | Testiranje pred proizvodnjo | Razvojna ekipa |
| Razvojni ključ | Lokalni razvoj | Posamezni razvijalec |
Vsak ključ ima določen obseg. Če razvijalec zapusti ekipo, se izbriše le njegov razvojni ključ – ostali ostanejo nedotaknjeni.
Ključne ugotovitve
GET /auth/management-keys/validationpreveri veljavnost tvojega upravljalnega ključa- Preverjanje vključi v zagon skripte in v nadzorovanje
- Redno revidiraj vse ključe, da odkriješ preširok dostop
- Loči ključe glede na okolje in odgovornost
- Takoj opozori ob neveljavnem ključu (potekel ali izbrisan)