Walidacja klucza zarządzania
Na tej stronie
Weryfikacja integralności Twoich kluczy
Walidacja klucza zarządzania to pierwsza linia obrony Twojej infrastruktury API. Przed każdą krytyczną operacją – wdrożeniem, rotacją, zmianami rozliczeniowymi – upewnij się, że Twój klucz jest ważny, a jego uprawnienia poprawne.
Punkt końcowy walidacji
GET /auth/management-keys/validation
curl "https://management-api.x.ai/auth/management-keys/validation" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY"
Odpowiedź potwierdza, że klucz jest aktywny, i zwraca informacje o zespole, uprawnieniach oraz powiązanych datach. Nie lekceważ daty wygaśnięcia: to jedyne dane, które pozwalają przewidzieć przerwę w działaniu, zamiast jej doświadczać, ponieważ wygasły klucz nie ostrzega – po prostu zwraca kod 401 przy pierwszym kolejnym wywołaniu.
Przypadki błędów
- 401 Unauthorized: Klucz jest nieprawidłowy, wygasł lub został usunięty
- 403 Forbidden: Klucz jest ważny, ale brakuje mu niezbędnych uprawnień do żądanej operacji
Integracja ze skryptami
Weryfikacja przy starcie
Walidacja podczas uruchamiania przenosi moment awarii tam, gdzie kosztuje ona najmniej. Bez tego sprawdzenia nieprawidłowy klucz ujawnia się przy pierwszym użytecznym wywołaniu – czyli w trakcie przetwarzania, czasem po wykonaniu już kilku kroków. Dzięki niemu skrypt zatrzymuje się w trzy sekundy z komunikatem wskazującym przyczynę.
import requests
import sys
MANAGEMENT_API = "https://management-api.x.ai"
MGMT_KEY = "xai-mgmt-..."
def validate_management_key():
"""Sprawdza, czy klucz zarządzania jest ważny."""
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("Klucz zarządzania ważny")
return True
elif response.status_code == 401:
print("BŁĄD: Klucz zarządzania nieprawidłowy lub wygasły")
return False
else:
print(f"BŁĄD: Nieoczekiwany status {response.status_code}")
return False
except requests.exceptions.RequestException as e:
print(f"BŁĄD POŁĄCZENIA: {e}")
return False
if not validate_management_key():
sys.exit(1)
Okresowy healthcheck
Okresowy healthcheck pokrywa to, co umyka walidacji przy starcie: usługi działające długo, uruchomione tygodnie temu, których klucz może wygasnąć lub zostać odwołany w międzyczasie. Sprawdzenie raz na godzinę wystarczy – punkt końcowy jest lekki i nie zużywa tokenów wnioskowania.
#!/bin/bash
# healthcheck-xai.sh — uruchamiany co godzinę przez crona
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: Klucz zarządzania xAI nieprawidłowy (HTTP $STATUS)"
# Wyślij alert (PagerDuty, Slack, e-mail)
fi
Audyt kluczy wnioskowania
Okresowy audyt odpowiada na trzy pytania, o które żaden alert nie zapyta za Ciebie: które klucze nadal mają dostęp wieloznaczny (wildcard), które nie mają limitów szybkości i które nie były używane od miesięcy. Dwa pierwsze to ryzyka, trzecie to okazja do porządków – a wszystkie trzy obsłużysz w jednym przebiegu.
import requests
from datetime import datetime
MANAGEMENT_API = "https://management-api.x.ai"
MGMT_KEY = "xai-mgmt-..."
TEAM_ID = "team-..."
def audit_api_keys():
"""Przeprowadza audyt wszystkich kluczy API dla zespołu."""
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"=== Audyt kluczy API — {datetime.now().strftime('%d/%m/%Y %H:%M')} ===")
print(f"Liczba kluczy łącznie: {len(keys)}")
for key in keys:
name = key.get("name", "Bez nazwy")
acls = key.get("acls", [])
expire = key.get("expireTime", "Nigdy")
created = key.get("createdAt", "N/D")
# Alerty
warnings = []
# Klucz z dostępem wieloznacznym
if "api-key:endpoint:*" in acls and "api-key:model:*" in acls:
warnings.append("PEŁNY DOSTĘP (wildcard)")
# Klucz bez daty wygaśnięcia
if expire == "Nigdy" or not expire:
warnings.append("BRAK WYGAŚNIĘCIA")
# Klucz bez limitów szybkości
if not key.get("qps") and not key.get("qpm"):
warnings.append("BRAK LIMITÓW SZYBKOŚCI")
status = " | ".join(warnings) if warnings else "OK"
print(f" [{name}] ACL: {len(acls)} | Wygasa: {expire} | {status}")
audit_api_keys()
Lista kontrolna bezpieczeństwa kluczy
Klucze zarządzania
Klucze zarządzania kontrolują wszystko inne – ich kompromitacja daje dostęp do tworzenia, modyfikowania i usuwania wszystkich kluczy wnioskowania. Wymagają więc najsurowszego traktowania: wyłącznego przechowywania w sejfie (vault), nigdy w postaci jawnej w kodzie czy wersjonowanej konfiguracji; dostęp ograniczony wyłącznie do administratorów infrastruktury, a nie deweloperów aplikacji; oraz regularnej walidacji przez GET /auth/management-keys/validation, najlepiej zautomatyzowanej jako healthcheck – wygasły klucz zarządzania wykryty w momencie, gdy pilnie go potrzebujesz, to najgorszy scenariusz operacyjny.
Klucze wnioskowania (klucze API)
W przypadku kluczy wnioskowania zasadą przewodnią jest izolacja: każda aplikacja otrzymuje własny klucz, nigdy klucz współdzielony między usługami – w przeciwnym razie rotacja skompromitowanego klucza łamie działanie wszystkich usług naraz, a analityka nie pozwala przypisać zużycia. Każdy klucz niesie restrykcyjne listy ACL dopasowane do rzeczywistego użycia (brak wildcardów w produkcji), limity szybkości skalowane do oczekiwanego ruchu oraz datę wygaśnięcia, gdy użycie jest tymczasowe – POC planowany na dwa tygodnie nie potrzebuje klucza wiecznego. Regularny audyt poprzez powyższy skrypt domyka pętlę: ujawnia zapomniane, nadmiernie uprzywilejowane lub wygasające klucze, zanim staną się problemem.
Zasada rozdzielania obowiązków
Utrzymuj wyraźny podział między kluczami:
| Typ | Zastosowanie | Kto ma dostęp |
|---|---|---|
| Klucz zarządzania | Administracja, rozliczenia, analityka | Administratorzy infrastruktury |
| Klucz produkcyjny | Wywołania API w produkcji | Aplikacja produkcyjna |
| Klucz stagingowy | Testy przedprodukcyjne | Zespół deweloperski |
| Klucz deweloperski | Praca lokalna | Poszczególny deweloper |
Każdy klucz ma określony zakres. Jeśli deweloper opuszcza zespół, usuwa się tylko jego klucz deweloperski – pozostałe pozostają nienaruszone.
Kluczowe wnioski
GET /auth/management-keys/validationsprawdza ważność Twojego klucza zarządzania- Zintegruj walidację ze startem skryptu i monitoringiem
- Regularnie audituj wszystkie klucze, by wykryć zbyt szeroki dostęp
- Rozdzielaj klucze według środowiska i odpowiedzialności
- Natychmiast alertuj przy nieprawidłowym kluczu (wygasłym lub usuniętym)