Przejdź do głównej treści
Polski— Wybierz język
Menu

Walidacja klucza zarządzania

Lekcja 13 z 14 Zaktualizowano 29 lipca 2026 Programista
Na tej stronie
  1. Weryfikacja integralności Twoich kluczy
  2. Punkt końcowy walidacji
  3. Integracja ze skryptami
  4. Audyt kluczy wnioskowania
  5. Lista kontrolna bezpieczeństwa kluczy
  6. Zasada rozdzielania obowiązków
  7. Kluczowe wnioski

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:

TypZastosowanieKto ma dostęp
Klucz zarządzaniaAdministracja, rozliczenia, analitykaAdministratorzy infrastruktury
Klucz produkcyjnyWywołania API w produkcjiAplikacja produkcyjna
Klucz stagingowyTesty przedprodukcyjneZespół deweloperski
Klucz deweloperskiPraca lokalnaPoszczegó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/validation sprawdza 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)