Wyświetlanie i modyfikowanie kluczy
Na tej stronie
Inwentarz Twoich kluczy API
Z czasem Twój zespół gromadzi klucze API dla różnych środowisk, projektów i członków zespołu. Management API pozwala wyświetlić wszystkie aktywne klucze, filtrować je według uprawnień oraz modyfikować ich ustawienia bez konieczności tworzenia nowych.
Wyświetlanie kluczy
Ten punkt końcowy jest wyjściem dla każdego audytu dostępu i często to właśnie tutaj odkrywasz rzeczywisty stan inwentarza: klucze utworzone do testów osiem miesięcy temu, klucz na nazwisko byłego członka zespołu, dwa klucze produkcyjne, przy których nikt nie wie, który jest używany. Zanim utworzysz cokolwiek nowego, najpierw wyświetl listę – klucz, którego potrzebujesz, może już istnieć.
curl "https://management-api.x.ai/auth/teams/$TEAM_ID/api-keys" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY"
Parametry żądania
- pageSize: liczba kluczy na stronę (domyślnie zwracane są wszystkie klucze)
- paginationToken: token do pobrania następnej strony, jeśli liczba kluczy przekracza rozmiar strony
- aclFilters: filtrowanie kluczy według określonych uprawnień
Filtrowanie według ACL
Możesz pobrać tylko klucze z określonym poziomem dostępu:
# Wyświetl tylko klucze z dostępem do czatu
curl "https://management-api.x.ai/auth/teams/$TEAM_ID/api-keys?aclFilters=api-key:endpoint:chat" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY"
To filtrowanie sprawia, że audyt jest wykonalny nawet przy więcej niż kilkunastu kluczach. W praktyce nasuwają się dwa pytania, na które odpowiada pojedyncze żądanie: kto może wywoływać najdroższy model i które klucze nadal posiadają symbol wieloznaczny (wildcard). To drugie jest najbardziej użyteczne – zapomniany symbol wieloznaczny w środowisku produkcyjnym to najczęstszy błąd konfiguracji i jednocześnie najbardziej podstępny.
Paginacja
Dla zespołów posiadających wiele kluczy użyj paginacji:
# Pierwsza strona z 10 kluczami
curl "https://management-api.x.ai/auth/teams/$TEAM_ID/api-keys?pageSize=10" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY"
# Następna strona z otrzymanym tokenem
curl "https://management-api.x.ai/auth/teams/$TEAM_ID/api-keys?pageSize=10&paginationToken=TOKEN_RECU" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY"
Modyfikowanie istniejącego klucza
Modyfikowanie zamiast ponownego tworzenia to nie tylko wygoda: tajny klucz pozostaje ten sam, więc nie jest konieczne żadne wdrożenie. Pozwala to dostosować limity lub ograniczyć uprawnienia bez przestoju w działaniu usługi – a w przypadku podejrzeń, zmniejszyć uprawnienia klucza w kilka sekund, przygotowując jednocześnie jego rotację.
curl -X PUT "https://management-api.x.ai/auth/api-keys/$API_KEY_ID" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "prod-backend-v3",
"acls": [
"api-key:endpoint:chat",
"api-key:endpoint:embed",
"api-key:model:grok-4.20-0309-reasoning"
],
"qps": 30,
"qpm": 1000,
"tpm": 3000000
}'
Co możesz zmodyfikować
- name: zmiana nazwy klucza, aby odzwierciedliła zmianę w jego wykorzystaniu
- acls: dodawanie lub usuwanie uprawnień (punkty końcowe, modele)
- qps / qpm / tpm: dostosowanie limitów szybkości (rate limits)
- expireTime: wydłużenie lub skrócenie okresu ważności
Czego nie możesz zmodyfikować
- Identyfikator klucza (
api_key_id) pozostaje stały - Tajny klucz nie ulega zmianie podczas modyfikacji (do tego służy rotacja)
- Nie można przenieść klucza do innego zespołu właścicielskiego
Sprawdzanie propagacji
Oto szczegół, który wyjaśnia połowę „błędów“ zgłaszanych po modyfikacji klucza: zmiana nie jest natychmiastowa na wszystkich serwerach. Świeżo utworzony klucz może przez chwilę zwracać błąd 401, rozszerzone ACL może jeszcze nie być aktywne – i szukasz błędu we własnym kodzie, podczas gdy wystarczyło poczekać. Punkt końcowy propagacji istnieje właśnie po to, aby rozwiać tę wątpliwość:
curl "https://management-api.x.ai/auth/api-keys/$API_KEY_ID/propagation" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY"
Ten punkt końcowy zwraca status propagacji klucza. Poczekaj na zakończenie propagacji przed użyciem klucza w środowisku produkcyjnym, szczególnie po modyfikacji uprawnień ACL.
Typowe scenariusze
Podniesienie klucza deweloperskiego do poziomu produkcyjnego
Przejście do środowiska produkcyjnego to najczęstszy scenariusz modyfikacji, a odruch tworzenia przy tej okazji nowego klucza jest kosztowny: musisz go wdrożyć wszędzie, zaktualizować sejfy (vaults), a stary klucz pozostaje w systemie w nieskończoność. Podniesienie limitów istniejącego klucza pozwala uniknąć wszystkich tych problemów.
curl -X PUT "https://management-api.x.ai/auth/api-keys/$API_KEY_ID" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "prod-chatbot",
"qps": 50,
"qpm": 2000,
"tpm": 5000000
}'
Ograniczenie klucza podejrzanego o kompromitację
W przypadku podejrzeń kolejność operacji ma znaczenie. Najpierw ogranicz uprawnienia – puste listy ACL, zerowe limity szybkości – to zatrzymuje wyciek jednym żądaniem, nie powodując żadnych nieodwracalnych szkód. Rotacja przychodzi później, offline, gdy już zidentyfikujesz, gdzie klucz był używany. Odwrócenie tej kolejności zostawia Cię z niedziałającą produkcją i dochodzeniem prowadzonym pod presją.
curl -X PUT "https://management-api.x.ai/auth/api-keys/$API_KEY_ID" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"acls": [],
"qps": 0,
"qpm": 0
}'
Kluczowe wnioski
GET /auth/teams/{teamId}/api-keyswyświetla listę wszystkich kluczy z paginacją i filtrowaniem ACLPUT /auth/api-keys/{apiKeyId}modyfikuje parametry bez zmiany tajnego kluczaGET /auth/api-keys/{apiKeyId}/propagationweryfikuje, czy zmiany są skuteczne- Używaj filtrowania ACL, aby regularnie przeprowadzać audyt dostępu w swoim zespole
- Po każdej modyfikacji sprawdź propagację przed użyciem klucza w środowisku produkcyjnym