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

Rotacja kluczy i ich cykl życia

Lekcja 7 z 12 Zaktualizowano 28 lipca 2026 Zaawansowany
Na tej stronie
  1. Dlaczego rotacja kluczy jest niezbędna
  2. Rotacja przez Management API
  3. Pełny cykl życia klucza
  4. Jaką strategię rotacji przyjąć?
  5. Dwadzieścia minut, by odzyskać kontrolę nad inwentarzem
  6. Kluczowe wnioski

Dlaczego rotacja kluczy jest niezbędna

Częstym zarzutem podczas szkoleń jest: „Mój klucz nigdy nie wyciekł, po co go zmieniać?“. Odpowiedź sprowadza się do jednego słowa: niepewność. Nigdy nie udowodnisz, że klucz nie został ujawniony – zapomniany na serwerze szczegółowy log, zrzut ekranu udostępniony w zgłoszeniu do wsparcia technicznego, skompromitowana stacja robocza developera sprzed sześciu miesięcy. Regularna rotacja zamienia tę niepewność w ograniczone ryzyko: nawet jeśli klucz został skopiowany bez Twojej wiedzy, przestanie działać przy następnej rotacji. To dokładnie taki tok rozumowania stosują audytorzy SOC 2; oczekują oni udokumentowanej polityki rotacji. Nazywamy to redukcją czasowej powierzchni ataku: im dłużej klucz istnieje, tym dłuższe jest okno eksploatacji w przypadku cichego kompromisu.

Zarządzanie API xAI zostało zaprojektowane tak, aby praktyka ta była bezbolesna: zapewnia dedykowany punkt końcowy, który pozwala obrócić klucz bez przepisywania konfiguracji.

Rotacja przez Management API

Punkt końcowy rotacji jest prosty:

POST https://management-api.x.ai/auth/api-keys/{apiKeyId}/rotate

Zanim użyjesz tego wywołania, upewnij się, że rozumiesz, co ono robi: generuje nowy tajny klucz dla istniejącego identyfikatora i trwale unieważnia stary, zachowując jednocześnie listy kontroli dostępu (ACL), limity przepustowości i konfiguracje przypisane do klucza. Rzecz, która zaskakuje zespoły przy pierwszym użyciu, polega na tym, że zmiana jest natychmiastowa i nieodwracalna. Jeśli Twoje środowisko produkcyjne używa tego klucza w momencie uruchomienia rotacji, w ciągu kilku sekund zacznie otrzymywać błędy uwierzytelniania. Nie ma okresu karencji ani możliwości cofnięcia zmian.

Dlatego w środowisku produkcyjnym zazwyczaj preferuje się procedurę dwuetapową, aby uniknąć jakichkolwiek przerw. Najpierw utwórz nowy klucz za pomocą POST /auth/teams/{teamId}/api-keys, z dokładnie tymi samymi uprawnieniami co stary. Następnie zweryfikuj jego propagację za pomocą GET /auth/api-keys/{newKeyId}/propagation – świeżo utworzony klucz nie jest natychmiast znany w całej infrastrukturze, a zbyt wczesne wdrożenie generuje mylące błędy. Kolejnym krokiem jest wdrożenie nowego klucza w backendach i przetestowanie, czy wywołania faktycznie z nim działają, a nie tylko czy wdrożenie zakończyło się bez błędów. Dopiero gdy masz to potwierdzenie, wyłącz stary klucz lub poczekaj, aż wygaśnie, zanim trwale usuniesz go poleceniem DELETE /auth/api-keys/{oldKeyId}.

Podejście „najpierw nowy klucz, potem usuń“ daje okres nakładania się, w którym oba klucze współistnieją: jeśli wdrożenie nie powiedzie się na jednym serwerze, nic nie ulega awarii. Rotacja w miejscu pozostaje dostępna, jeśli chcesz zachować ten sam identyfikator klucza:

curl -X POST \
  "https://management-api.x.ai/auth/api-keys/key_abc123/rotate" \
  -H "Authorization: Bearer $MANAGEMENT_KEY"

W tym przypadku zaplanuj natychmiastową aktualizację backendów, ponieważ stary klucz przestaje działać w chwili zakończenia wywołania.

Pełny cykl życia klucza

Dobrze zarządzany klucz ma czterozaktową historię. Podczas tworzenia, przez POST /auth/teams/{teamId}/api-keys, definiujesz jego nazwę, listy ACL i – co jest nawykiem do wyrobienia – datę wygaśnięcia:

{
  "name": "prod-chat-service",
  "acls": ["api-key:endpoint:chat", "api-key:model:grok-4.3"],
  "expireTime": "2026-12-31T23:59:59Z"
}

Klucz bez expireTime to klucz, który będzie żył wiecznie, jeśli nikt o nim nie pomyśli; klucz z datą wygaśnięcia zmusza Twój zespół do zadania pytania o odnowienie w ustalonym terminie. Następnie приходит monitoring: GET /v1/api-key informuje o statusie klucza (api_key_blocked, api_key_disabled), a konsola xAI udostępnia dane dotyczące użycia i anomalii. W przypadku modyfikacji w trakcie cyklu życia – zmiany nazwy, dostosowania ACL, zaostrzenia limitów przepustowości, przesunięcia daty wygaśnięcia – użyj PUT https://management-api.x.ai/auth/api-keys/{api_key_id}. Na końcu, usunięcie przez DELETE /auth/api-keys/{apiKeyId} jest trwałe i nieodwracalne: każda aplikacja używająca tego klucza przestaje działać natychmiast. Przed usunięciem upewnij się, że żadna zapomniana usługa – miesięczne zadanie cron, skrypt raportujący – nadal od niego nie zależy.

Jaką strategię rotacji przyjąć?

Właściwa częstotliwość zależy od wrażliwości Twojego środowiska. Rotacja miesięczna jest obowiązkowa w wysoce wrażliwych kontekstach, takich jak finanse czy ochrona zdrowia, gdzie okno ekspozycji musi pozostać minimalne. Rotacja kwartalna odpowiada standardowym środowiskom profesjonalnym: wystarczająco częsta, by być skuteczna, i wystarczająco rzadka, by nie obciążać zespołów. Rotacja roczna, w połączeniu z określoną datą wygaśnięcia, to akceptowalne minimum – poniżej tego poziomu Twoja polityka rotacji nie jest tak naprawdę polityką. We wszystkich przypadkach automatyzacja za pomocą zaplanowanego skryptu uwalnia Cię od polegania na pamięci administratora.

Do tego harmonogramu dodaje się rotację sterowaną zdarzeniami, wyzwalaną przez okoliczności, a nie datę. Najczęściej uruchamiasz ją w momencie odejścia pracownika, który miał dostęp do kluczy: nawet jeśli rozstanie jest pokojowe, klucz, który znał, musi zostać obrócony tego samego dnia – to zasada higieny bezpieczeństwa, a nie oznaka braku zaufania. Zrób to samo w przypadku podejrzenia kompromisu, incydentu bezpieczeństwa w Twojej infrastrukturze lub zmiany dostawcy, który miał dostęp do Twoich systemów.

Dwadzieścia minut, by odzyskać kontrolę nad inwentarzem

Najlepszym momentem na odkrycie rzeczywistego stanu Twoich kluczy nie jest dzień audytu. Dlatego teraz wyświetl listę wszystkich kluczy za pomocą GET /auth/teams/{teamId}/api-keys i zidentyfikuj te bez daty wygaśnięcia, aby dodać im expireTime. Dla każdego z nich zadaj sobie pytanie, czy jego listy ACL odpowiadają ścisłemu minimum wymaganemu przez aplikację, która go używa; klucz utworzony dla prototypu i przeniesiony do produkcji prawie zawsze posiada zbyt wiele uprawnień.

Następnie usuń nieużywane klucze, ponieważ każdy aktywny klucz to potencjalny wektor ataku, a klucz, o którym nikt nie pamięta, jest najgorszy ze wszystkich: nikt nie zauważy jego nieprawidłowego użycia. Na koniec udokumentuj, kto ma dostęp do którego klucza i dlaczego. Ten dokument, bardziej niż same klucze, jest tym, co wyciągniesz podczas następnego audytu.

Kluczowe wnioski

  • Punkt końcowy POST /auth/api-keys/{id}/rotate unieważnia stary klucz trwale, bez okresu karencji
  • W środowisku produkcyjnym preferuj utworzenie nowego klucza, a następnie usunięcie starego, aby uniknąć przerw
  • Zawsze ustawiaj datę wygaśnięcia dla swoich kluczy
  • Automatyzuj rotację za pomocą zaplanowanego skryptu (miesięcznie, kwartalnie lub rocznie w zależności od wrażliwości)
  • Uruchamiaj natychmiastową rotację przy każdej zmianie personelu lub incydencie bezpieczeństwa