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

Listy kontroli dostępu (ACL) i zasada najmniejszych uprawnień

Lekcja 8 z 12 Zaktualizowano 28 lipca 2026 Zaawansowany
Na tej stronie
  1. Zasada najmniejszych uprawnień w kontekście API
  2. System ACL w xAI
  3. Limity przepustowości: dodatkowa warstwa bezpieczeństwa
  4. Strategia osobnego klucza dla każdego środowiska
  5. Weryfikacja i audyt uprawnień
  6. Kluczowe wnioski

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