Listy kontroli dostępu (ACL) i zasada najmniejszych uprawnień
Na tej stronie
Zasada najmniejszych uprawnień w kontekście API
Zasada najmniejszych uprawnień to jedna z najstarszych koncepcji w dziedzinie cyberbezpieczeństwa: każdy komponent systemu powinien mieć dostęp wyłącznie do zasobów ściśle niezbędnych do jego działania. Pomysł ten jest intuicyjny, gdy odniesiesz go do świata fizycznego – nie wręczasz klucza uniwersalnego do budynku osobie podlewającej rośliny w holu. W odniesieniu do kluczy API xAI oznacza to, że każdy klucz musi być ograniczony wyłącznie do tych punktów końcowych (endpointów) i modeli, których aplikacja go używająca rzeczywiście potrzebuje. Jeśli taki klucz kiedyś wycieknie, napastnik przejmuje jego uprawnienia: klucz ograniczony do czatu z jednym modelem wyrządzi nieskończenie mniej szkód niż klucz otwierający dostęp do całego katalogu.
xAI wdraża tę zasadę dzięki granulowanemu systemowi list kontroli dostępu (ACL), który szczegółowo omówimy poniżej.
System ACL w xAI
Listy ACL mają format api-key:{type}:{value}. Dwa typy dotyczą Cię na co dzień: api-key:endpoint:{endpoint} ogranicza dostępne punkty końcowe, a api-key:model:{model_id} ogranicza dostępne modele. Istnieje również symbol wieloznaczny (wildcard) api-key:endpoint:*, który przyznaje dostęp do wszystkich punktów końcowych – wygodny w fazie deweloperskiej, ale zabroniony w środowisku produkcyjnym, właśnie dlatego, że niweczy korzyści płynące z zasady najmniejszych uprawnień.
Punkty końcowe, które możesz autoryzować indywidualnie, to: chat (uzupełnianie czatu, zdecydowanie najczęstszy przypadek), embed (generowanie osadzeń), image (generowanie i edycja obrazów), models (konsultacja listy modeli), tokenize (tokenizacja tekstu), documents (zarządzanie dokumentami) oraz sample (próbkowanie).
Zobaczmy, jak wygląda to w praktyce. Wyobraź sobie bota obsługi klienta, który korzysta wyłącznie z modelu grok-4.3 w trybie czatu. Jego idealny klucz wygląda następująco:
{
"name": "support-chatbot-prod",
"acls": [
"api-key:endpoint:chat",
"api-key:model:grok-4.3"
],
"qps": 5,
"qpm": 100,
"tpm": 500000,
"expireTime": "2026-12-31T23:59:59Z"
}
Traktuj tę konfigurację jak umowę: klucz może uzyskać dostęp wyłącznie do punktu końcowego czatu – żadnych obrazów, żadnych osadzeń, więc nie ma możliwości nadużycia w tych celach. Może korzystać tylko z modelu grok-4.3, co zapobiega przypadkowym (lub złośliwym) wywołaniom droższych modeli. Jest ograniczony do 5 żądań na sekundę i 100 na minutę, a jego ważność wygaśnie w znanym terminie. Jeśli któryś z programistów w projekcie spróbuje dodać generowanie obrazów bez powiadomienia zespołu, API odmówi wykonania: ograniczenie techniczne wymusza decyzję architektoniczną.
Limity przepustowości: dodatkowa warstwa bezpieczeństwa
Listy ACL odpowiadają na pytanie „co“, natomiast limity przepustowości odpowiadają na pytanie „ile“. QPS (Queries Per Second) ogranicza liczbę żądań na sekundę: to Twoja ochrona przed przypadkowymi skokami obciążenia – nieskończoną pętlą wprowadzoną podczas refaktoryzacji w piątkowy wieczór lub atakiem DDoS odbijającym się od Twojej aplikacji. QPM (Queries Per Minute) wygładza ruch w dłuższym okresie i wyłapuje nadużycia, które mieściłyby się w limicie QPS. TPM (Tokens Per Minute) z kolei ogranicza wolumen zużywanych tokenów: chroni przed pojedynczymi, bardzo długimi żądaniami – np. gdy użytkownik wklei do Twojego bota dokument liczący 200 stron – które wyczerpałyby Twój budżet w ciągu kilku minut, nie przekraczając przy tym autoryzowanej liczby żądań.
Strategia osobnego klucza dla każdego środowiska
W praktyce nie konfigurujesz jednego klucza, lecz rodzinę kluczy, przy czym każde środowisko ma swoją własną logikę. W środowisku deweloperskim odwracasz logikę produkcyjną: szeroki dostęp, ścisłe limity.
{
"name": "dev-team-alpha",
"acls": ["api-key:endpoint:*", "api-key:model:*"],
"qps": 2,
"qpm": 30,
"tpm": 100000,
"expireTime": "2026-06-30T23:59:59Z"
}
Programiści mogą eksplorować wszystko, ale niskie limity zapobiegają niespodziankom na fakturze, jeśli test wymknie się spod kontroli. W środowisku stagingowym, przeciwnie, replikujesz dokładnie listy ACL z produkcji (api-key:endpoint:chat, api-key:model:grok-4.3, QPS 5, QPM 100, TPM 500000): to jedyny sposób, by wykryć problemy z uprawnieniami wcześniej – jeśli kod na stagingu próbuje wykonać wywołanie, które produkcja odrzuci, lepiej dowiedzieć się o tym teraz niż w pierwszej godzinie po uruchomieniu. Klucz produkcyjny łączy natomiast ścisłe uprawnienia ze środowiska staging z limitami dopasowanymi do rzeczywistego ruchu (np. QPS 20, QPM 600, TPM 2000000) oraz zaplanowaną datą wygaśnięcia – "expireTime": "2027-03-31T23:59:59Z" dla klucza o nazwie prod-chatbot-v2.
Weryfikacja i audyt uprawnień
Aby sprawdzić, co dokładnie może zrobić aktywny klucz, wykonaj zapytanie do API przy użyciu samego klucza:
curl https://api.x.ai/v1/api-key \
-H "Authorization: Bearer $XAI_API_KEY"
Odpowiedź zawiera listę efektywnych list ACL, statusy api_key_blocked i api_key_disabled, zamaskowaną wersję klucza (redacted_api_key) oraz team_id. Wyrobij sobie nawyk regularnego porównywania tych list ACL z rzeczywistymi potrzebami aplikacji: uprawnienia mają tendencję do kumulowania się w czasie i nigdy nie zmniejszają się spontanicznie. Po stronie modeli punkt końcowy GET /auth/teams/{teamId}/models zwraca listę modeli dostępnych dla Twojego zespołu wraz z ich cennikiem – są to cenne informacje pozwalające zdefiniować odpowiednie listy ACL dla modeli i wykluczyć drogie modele, z których nie korzystasz.
Aby utrwalić wszystkie te zasady, przeprowadź pełny audyt swoich kluczy. Sporządź listę aktywnych kluczy dla każdego zespołu, a następnie odpytaj każdy z nich: czy jego listy ACL są minimalne, bez symboli wieloznacznych w produkcji? Czy jego limity przepustowości są rozsądne? Czy ustawiono datę wygaśnięcia? Czy jego nazwa identyfikuje aplikację i środowisko – „prod-chatbot-v2“ opowiada historię, „key-test-2“ nie mówi nic? Usuń klucze osierocone i udokumentuj wynik: dokument ten posłuży jako punkt wyjścia do kolejnego audytu, a Ty od razu zobaczysz, co uległo zmianie w międzyczasie.
Kluczowe wnioski
- Każdy klucz musi mieć restrykcyjne listy ACL: tylko niezbędne punkty końcowe i modele
- Nigdy nie używaj symbolu wieloznacznego
*w środowisku produkcyjnym - Łącz listy ACL z limitami przepustowości (QPS, QPM, TPM) dostosowanymi do rzeczywistego użycia
- Twórz odrębne klucze dla każdego środowiska (dev, staging, prod) i każdej aplikacji – staging powinien mieć takie same listy ACL jak produkcja
- Regularnie audituj uprawnienia swoich aktywnych kluczy za pomocą
GET /v1/api-key