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

Rotacja i usuwanie kluczy

Lekcja 4 z 14 Zaktualizowano 29 lipca 2026 Programista
Na tej stronie
  1. Rotacja: Odnowienie bez przerw
  2. Przeprowadzanie rotacji
  3. Usuwanie klucza
  4. Automatyzacja rotacji
  5. Kluczowe wnioski

Rotacja: Odnowienie bez przerw

Rotacja kluczy to kluczowa praktyka bezpieczeństwa. Generuje ona nowy klucz tajny, który zastępuje stary, bez usuwania samego klucza. Stary sekret zostaje natychmiast i trwale unieważniony.

Przeprowadzanie rotacji

Rotacja rozwiązuje problem, którego nie da się rozwiązać przez usunięcie: odnowienie sekretu bez utraty tożsamości klucza. Jego listy kontroli dostępu (ACL), limity szybkości i nazwa przetrwają tę operację, więc nie musisz niczego konfigurować ponownie – w Twoim magazynie zmienia się tylko sekret. Dzięki temu regularna rotacja staje się praktyczna; ręczne odtworzenie klucza wymagałoby za każdym razem ponownej konfiguracji wszystkiego.

POST /auth/api-keys/{apiKeyId}/rotate
curl -X POST "https://management-api.x.ai/auth/api-keys/$API_KEY_ID/rotate" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY"

Zachowanie podczas rotacji

  • Stary klucz tajny zostaje natychmiast unieważniony – każde żądanie używające go zakończy się błędem 401
  • Generowany jest nowy klucz tajny i zwracany w odpowiedzi
  • ID klucza (apiKeyId), nazwa, listy ACL i limity szybkości pozostają niezmienione
  • Nowy klucz tajny jest wyświetlany tylko raz – zapisz go niezwłocznie

Bezpieczny proces rotacji

Jeden element tej procedury zasługuje na szczególne podkreślenie, ponieważ często zaskakuje użytkowników: stary sekret jest unieważniany natychmiast. Nie ma okresu karencji, w którym oba sekrety działałyby jednocześnie. Wszystkie usługi nadal używające starej wartości przestaną działać w ułamku sekundy po wywołaniu operacji. Dyktuje to kolejność sześciu poniższych kroków: przygotuj swój magazyn przed uruchomieniem rotacji, a nie po niej.

  1. Przygotuj swoją infrastrukturę do przyjęcia nowego klucza (zmienna środowiskowa, magazyn)
  2. Przeprowadź rotację przez API
  3. Zaktualizuj sekret w swoim magazynie natychmiast
  4. Wdróż ponownie swoje usługi z nowym kluczem
  5. Zweryfikuj, czy żądania kończą się sukcesem przy użyciu nowego klucza
  6. Zweryfikuj propagację poprzez GET /auth/api-keys/{apiKeyId}/propagation

Kiedy przeprowadzać rotację

Trzy sytuacje wymagają rotacji, każda z inną pilnością. Podejrzenie wycieku wymaga natychmiastowej rotacji: członek zespołu mający dostęp do klucza odchodzi, log zawierający klucz zostaje publicznie ujawniony lub repozytorium Git zawiera klucz w postaci zwykłego tekstu. W takich przypadkach każda godzina oczekiwania to godzina ekspozycji, więc przeprowadź rotację przed zakończeniem analizy incydentu. Rotacja oparta na polityce ma charakter prewencyjny: co 30, 60 lub 90 dni, w zależności od wymagań bezpieczeństwa, ogranicza czas życia klucza, który mógł wyciec niezauważony. Wreszcie, zmiany w środowisku – migracja infrastruktury lub zmiana dostawcy – są naturalną okazją do rozpoczęcia pracy od nowa z czystymi kluczami, zamiast przenoszenia starych do kontekstu, dla którego nie zostały zaprojektowane.

Usuwanie klucza

Usunięcie jest trwałe i nieodwracalne. Pytanie, które należy sobie zadać przed usunięciem, nie brzmi: „Czy ten klucz został skompromitowany?“, ale: „Czy nadal potrzebuję tego zakresu dostępu?“. Jeśli odpowiedź brzmi „tak“, potrzebujesz rotacji: neutralizuje ona ujawniony sekret, zachowując jednocześnie konfigurację. Usunięcie jest uzasadnione tylko w przypadku klucza, który nie jest już potrzebny – zakończony projekt, były dostawca lub wycofane środowisko.

DELETE /auth/api-keys/{apiKeyId}
curl -X DELETE "https://management-api.x.ai/auth/api-keys/$API_KEY_ID" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY"

Konsekwencje usunięcia

  • Klucz i wszystkie jego parametry zostają trwale usunięte
  • Wszystkie żądania używające tego klucza natychmiast zakończą się niepowodzeniem
  • Akcja jest nieodwracalna – będziesz musiał utworzyć nowy klucz z nowymi parametrami
  • Historia użycia klucza pozostaje dostępna w analityce

Rotacja kontra usunięcie

AspektRotacjaUsunięcie
Klucz nadal istniejeTakNie
Wygenerowano nowy sekretTakNie
Listy ACL zachowaneTakNie
Limity zachowaneTakNie
OdwracalnośćNie (stary sekret utracony)Nie (klucz usunięty)
Typowe zastosowanieRegularne odnawianiePrzestarzały klucz lub potwierdzony kompromis

Automatyzacja rotacji

Automatyzacja rotacji ma sens tylko wtedy, gdy zapis do magazynu jest częścią tego samego skryptu, bez żadnej ręcznej interwencji pomiędzy tymi krokami. W przeciwnym razie jedynie przenosisz ryzyko: sekret wygenerowany maszynowo i kopiowany ręcznie częściej trafi do schowka lub historii terminala niż klucz utworzony z konsoli.

import requests
import json

MANAGEMENT_API = "https://management-api.x.ai"
MGMT_KEY = "xai-mgmt-..."
KEY_ID = "key-123"

# Rotacja
response = requests.post(
    f"{MANAGEMENT_API}/auth/api-keys/{KEY_ID}/rotate",
    headers={"Authorization": f"Bearer {MGMT_KEY}"}
)

new_key = response.json()
new_secret = new_key.get("secret")

# Zapisz w swoim magazynie (przykład z plikiem .env)
# W środowisku produkcyjnym użyj Vault, AWS Secrets Manager itp.
print(f"Wygenerowano nowy klucz. Zaktualizuj swój magazyn.")

Zaplanowana rotacja

Zintegruj rotację ze swoim potokiem CI/CD lub zadaniem cron:

# Przykład Cron: rotacja 1. dnia każdego miesiąca o 3:00
0 3 1 * * /opt/scripts/rotate-xai-keys.sh

Kluczowe wnioski

  • POST /auth/api-keys/{apiKeyId}/rotate unieważnia stary sekret i generuje nowy
  • Unieważnienie starego sekretu jest natychmiastowe i trwałe
  • DELETE /auth/api-keys/{apiKeyId} usuwa klucz nieodwracalnie
  • Preferuj rotację zamiast usuwania, aby zachować istniejące listy ACL i limity
  • Automatyzuj rotację za pomocą skryptu i magazynu sekretów
  • Zawsze weryfikuj propagację po przeprowadzeniu rotacji