API Keys

Dzięki osobistemu kluczowi API Twoje skrypty i programy korzystają z AITEZA w Twoim imieniu, bez Twojego hasła. Traktuj klucze API jak hasła: kto ma klucz, może działać w Twoim imieniu w granicach tego klucza.

Istnieją dwa typy kluczy:

Kto może tworzyć klucze API#

• Potrzebujesz roli Klucze API. Administratorzy organizacji nadają ją na stronie Osoby (zobacz Role). Jak każda rola obowiązuje ona we wszystkich organizacjach, do których należysz. Każdy klucz działa jednak tylko w jednej organizacji.
• Z tą rolą Ustawienia pokazują w sekcji Osobiste stronę Klucze API, a na stronie Moje konto w sekcji Możesz pojawia się „Tworzyć osobiste klucze API”. Jeśli strona nie pojawi się po nadaniu roli, wyloguj się i zaloguj ponownie.
• Jeśli na stronie widnieje komunikat „Klucze API nie są włączone”, Twoja instalacja nie oferuje osobistych kluczy API. Zwróć się do operatorów swojej instalacji.

Dwa typy kluczy#

API AITEZA#

Klucz AITEZA wywołuje REST API AITEZA jako Ty, w organizacji, w której pracowałeś podczas jego tworzenia. Nigdy nie może więcej niż Ty i działa jak zwykły członek tej organizacji:

• Bez ról administracyjnych. Twoje role administracyjne (Administrator organizacji, Administrator przestrzeni danych, administrator platformy) nie dotyczą klucza. Ma on dostęp tylko do przestrzeni danych, w których jesteś właścicielem, edytorem lub przeglądającym, bezpośrednio lub przez grupę, a nie do wszystkich przestrzeni danych organizacji.
• Tylko ta organizacja. Klucz nie widzi Twoich pozostałych organizacji. Na przykład GET /api/identity/me/tenants zwraca tylko organizację klucza.
• Wszystkie Twoje czaty i pliki. Twoje własne czaty i Twoje własne pliki, czyli przesłane przez Ciebie i wygenerowane dla Ciebie przez AITEZA, nie są w AITEZA przypisane do żadnej organizacji. Klucz może więc odczytać je wszystkie, także te z Twoich pozostałych organizacji. Klucz z dostępem Odczyt i zapis może je też zmieniać i usuwać.

Jeśli Twoje uprawnienia się zmienią, zmienia się też to, do czego ma dostęp klucz.

Podczas tworzenia klucza wybierasz jego dostęp:

To, co może klucz z dostępem Odczyt, zależy od metody HTTP zapytania. Wszystko, co coś tworzy, zmienia lub usuwa, w tym wysłanie wiadomości na czacie, wymaga dostępu Odczyt i zapis. Dotyczy to też niektórych funkcji, które tylko pobierają dane, ale wysyłają zapytanie metodą POST, np. wyszukiwania w przestrzeniach danych.

Zapytania do modeli AI wysłane kluczem AITEZA, np. wiadomości na czacie, liczą się do Twojego zużycia, tak samo jak Twoje zapytania w przeglądarce.

LiteLLM, zgodny z OpenAI#

Klucz LiteLLM daje programom zgodnym z OpenAI bezpośredni dostęp do modeli AI przez https://<Twój host AITEZA>/v1. Działa z wieloma narzędziami i bibliotekami obsługującymi API OpenAI: ustawiasz w nich bazowy URL i klucz.

• Tylko Twoje modele. Klucz może korzystać z modeli, z których możesz korzystać w organizacji, z uwzględnieniem wyboru Twoich grup (zobacz Z jakich modeli może korzystać dana osoba). Jeśli to się zmieni, klucz się dostosuje. Używaj nazw modeli, które zwraca /v1/models; mogą się różnić od nazw w wyborze modelu w AITEZA.
• Tylko wywołania modeli. Klucz może wywoływać i wyświetlać modele, ale nie może korzystać z innych funkcji, takich jak pliki, batche czy asystenci (zobacz Wywoływanie modeli kluczem LiteLLM).
• Miesięczny limit. Administratorzy Twojej organizacji ustalają, ile każda osoba może wykorzystać kluczami LiteLLM w miesiącu. Limit dotyczy Ciebie, a nie każdego klucza osobno: obejmuje łącznie wszystkie Twoje klucze LiteLLM w organizacji, także klucze unieważnione lub wygasłe w tym miesiącu. Strona Klucze API pokazuje Twój limit i wykorzystanie Twoich kluczy w tym miesiącu (zobacz Strona Klucze API). Gdy Twoje klucze wyczerpią limit, ich zapytania są odrzucane, dopóki limit nie zacznie się od nowa na początku następnego miesiąca. Nadal możesz tworzyć klucze LiteLLM, ale dzielą one ten sam limit.
• Koszty. Zapytania wysłane Twoimi kluczami LiteLLM pojawiają się na Twojej stronie Moje zużycie oraz na stronie Zużycie organizacji pod Twoim nazwiskiem.
• Dostępność. Ten typ możesz wybrać tylko wtedy, gdy Twoja instalacja oferuje klucze LiteLLM, a administratorzy Twojej organizacji ustalili miesięczny limit. W przeciwnym razie opcja jest wyłączona i podaje powód: „Niedostępne w tej instalacji” lub „Twoja organizacja nie ustaliła jeszcze limitu”. Musisz też mieć w organizacji dostęp do co najmniej jednego modelu.

Klucze AITEZA nie działają pod adresem /v1, a klucze LiteLLM nie działają z REST API AITEZA.

Strona Klucze API#

Otwórz menu profilu, wybierz Ustawienia, a następnie w sekcji Osobiste stronę Klucze API. Strona pokazuje Twoje klucze w organizacji, w której aktualnie pracujesz (zobacz Praca w kilku organizacjach):

• Aktywne z liczbą kluczy, np. „Aktywne (2)”: klucze, których można używać.
• Wygasłe lub unieważnione: klucze, które przestały obowiązywać. Pozostają widoczne przez 30 dni od zakończenia.

Jeśli Twoja organizacja oferuje klucze LiteLLM, strona pokazuje też Twój miesięczny limit dla nich i łączne wykorzystanie wszystkich Twoich kluczy LiteLLM w tym miesiącu, np. „Miesięczny limit Twoich kluczy LiteLLM: 25,00 € · 3,10 € wykorzystano w tym miesiącu”.

Przy każdym kluczu widzisz:

• jego nazwę,
• typ (API AITEZA lub LiteLLM) i początek klucza, np. azk_AbC1dEf2… lub sk-azp-AbC1dEf2…, aby odróżnić klucze od siebie,
• przy kluczach AITEZA dostęp (Odczyt lub Odczyt i zapis), przy kluczach LiteLLM wykorzystanie tego klucza w bieżącym miesiącu, np. „3,10 € wykorzystano”,
• kiedy go utworzono, kiedy wygasa („Wygasa …”) lub się zakończył („Wygasł …”, „Unieważniono …”) oraz kiedy go ostatnio użyto („Ostatnio użyto …” lub „Jeszcze nie użyto”).

Tworzenie klucza#

Okno zaczyna od ustawień API AITEZA, Odczyt i 90 dni. Wybieraj najkrótszą wystarczającą ważność; 30 dni to najbezpieczniejszy wybór.

• Nazwa może mieć do 100 znaków i musi różnić się od nazw Twoich pozostałych aktywnych kluczy.
• Możesz mieć jednocześnie do 10 aktywnych kluczy, liczonych łącznie we wszystkich Twoich organizacjach, chyba że Twoja instalacja ustala inną liczbę.
• Klucza nie można przedłużyć. Przed jego wygaśnięciem utwórz nowy klucz, przełącz na niego program i unieważnij stary.
• Aby używać klucza w innej organizacji, najpierw przejdź do tej organizacji i utwórz klucz w niej.

Jeśli AITEZA nie może utworzyć klucza, okno podaje powód:

Klucz jest wyświetlany tylko raz#

Dopóki klucz jest wyświetlany, kliknięcie poza oknem ani klawisz Escape go nie zamykają, więc nie stracisz klucza przez przypadek. Zamknij okno przyciskiem Gotowe, gdy zapiszesz klucz.

Pod kluczem sekcja Jak używać klucza pokazuje pierwsze wywołanie do wypróbowania, z właściwym adresem Twojej instalacji. Kopiuj przykład je kopiuje. Dla klucza LiteLLM okno pokazuje też Bazowy URL dla programów zgodnych z OpenAI.

Bezpieczne przechowywanie kluczy#

• Przechowuj klucz w menedżerze haseł lub w magazynie sekretów systemu, na którym działa Twój program.
• Przekazuj go programowi w zmiennej środowiskowej, np. AITEZA_API_KEY lub OPENAI_API_KEY, a nie jako część programu.
• Nigdy nie umieszczaj klucza w kodzie źródłowym, plikach konfiguracyjnych w systemie kontroli wersji, wiadomościach na czacie, e-mailach, zgłoszeniach ani promptach. Nie przekazuj go innym: każdy, kto potrzebuje klucza, tworzy własny.
• Używaj jednego klucza na program lub cel, aby móc unieważnić jeden bez wpływu na pozostałe.
• Pamiętaj, że klucz AITEZA ma dostęp do wszystkich Twoich własnych czatów i plików, także tych z Twoich pozostałych organizacji (zobacz API AITEZA). Kto ma klucz z dostępem Odczyt i zapis, może je też zmieniać i usuwać.
• Wybieraj Odczyt i najkrótszą wystarczającą ważność.
• Jeśli klucz mógł trafić w niepowołane ręce, natychmiast go unieważnij.
• Zresetowanie hasła nie unieważnia Twoich kluczy. Jeśli Twoje konto mogło zostać przejęte, unieważnij swoje klucze albo poproś administratora organizacji, aby wybrał dla Ciebie Wyloguj wszędzie; to również unieważnia wszystkie Twoje klucze.

Używanie klucza#

Przykłady używają adresu aiteza.example.com. Zastąp go adresem swojej instalacji AITEZA; okno wyświetlane po utworzeniu klucza pokazuje właściwy adres. Przykłady oczekują klucza w zmiennej środowiskowej. Aby ustawić zmienną tak, by klucz nie trafił do historii powłoki, wpisz np.:

read -rs AITEZA_API_KEY && export AITEZA_API_KEY

Następnie wklej klucz i naciśnij Enter. Klucz nie pojawi się na ekranie.

Wywoływanie API AITEZA#

Wysyłaj klucz jako token typu Bearer w nagłówku Authorization. To wywołanie wyświetla modele, z których możesz korzystać:

curl https://aiteza.example.com/api/models \
  -H "Authorization: Bearer $AITEZA_API_KEY"

Klucz możesz też wysłać w nagłówku X-API-Key:

curl https://aiteza.example.com/api/models \
  -H "X-API-Key: $AITEZA_API_KEY"

Aby wypróbować punkty końcowe w przeglądarce, otwórz dokumentację API pod adresem https://<host AITEZA>/doc/swagger-ui.html, wybierz Authorize i wpisz klucz w polu api_key. Punkty końcowe, z których klucze nie mogą korzystać, pokazują tam tylko logowanie przez Keycloak.

• Wysyłaj w każdym zapytaniu dokładnie jeden klucz i żadnego innego tokenu logowania.
• Nie musisz wybierać organizacji: klucz zawsze działa w swojej. Jeśli Twój program mimo to wysyła nagłówek X-Tenant-Id, musi on wskazywać organizację klucza.
• Każdy klucz może wysłać najwyżej 60 zapytań na minutę, chyba że Twoja instalacja ustala inną liczbę. Kolejne zapytania są odrzucane ze statusem 429 (zobacz Komunikaty o błędach).
• Twoja instalacja może też ustalić hojny limit na osobę. Obejmuje on wszystkie Twoje zapytania łącznie, ze wszystkich kluczy i po zalogowaniu w AITEZA, i ogranicza liczbę zapytań na minutę oraz zapytań wykonywanych jednocześnie. Gdy jest włączony, każda odpowiedź podaje w nagłówku RateLimit liczbę wolnych zapytań i liczbę sekund, po których znów wszystkie będą wolne; RateLimit-Policy podaje sam limit.
• To, co robisz za pomocą klucza, jest zapisywane w Dzienniku audytu pod Twoim nazwiskiem. Szczegóły zdarzenia podają klucz (apiKey i apiKeyName). Zapytania, które AITEZA odrzuca z powodu ograniczeń klucza, np. funkcja administracyjna, inna organizacja albo zmiana kluczem z dostępem Odczyt, są zapisywane jako „Odmowa dostępu”, dzięki czemu nadużycie zgubionego klucza jest widoczne.

Wywoływanie modeli kluczem LiteLLM#

Jako bazowego URL użyj https://<Twój host AITEZA>/v1. Wiele programów zgodnych z OpenAI samodzielnie odczytuje klucz ze zmiennej środowiskowej OPENAI_API_KEY. To wywołanie wyświetla modele, z których może korzystać klucz:

curl https://aiteza.example.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY"

Zapytanie czatu, z jedną z wyświetlonych nazw modeli w miejscu MODEL_NAME:

curl https://aiteza.example.com/v1/chat/completions \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "MODEL_NAME", "messages": [{"role": "user", "content": "Dzień dobry"}]}'

To samo z biblioteką OpenAI dla Pythona (pip install openai):

import os

from openai import OpenAI

client = OpenAI(
    base_url="https://aiteza.example.com/v1",
    api_key=os.environ["OPENAI_API_KEY"],
)

response = client.chat.completions.create(
    model="MODEL_NAME",
    messages=[{"role": "user", "content": "Dzień dobry"}],
)
print(response.choices[0].message.content)

• Wysyłaj klucz dokładnie raz, jako Authorization: Bearer sk-azp-…. Biblioteki klienckie OpenAI robią to same. Inne sposoby wysłania są odrzucane ze statusem 401, np. klucz w adresie, klucz podany dwa razy, Basic zamiast Bearer albo inny nagłówek z dodatkowym tekstem.
• Klucz może wywoływać tylko endpointy modeli: chat completions, completions, responses, embeddings, listę modeli, moderations, rerank, audio (transkrypcja, tłumaczenie, synteza mowy) i obrazy (generowanie, edycja, warianty). Inne endpointy, np. pliki, batche, vector stores, asystenci, fine-tuning czy MCP, są odrzucane ze statusem 403.
• Treść zapytania, z wyjątkiem przesyłania plików, musi być pojedynczym obiektem JSON bez powtórzonych pól, a model musi należeć do Twoich modeli. Automatyczne przełączanie LiteLLM na inne modele (fallback) jest dla tych kluczy wyłączone.
• Każdy klucz LiteLLM może wykonywać najwyżej 4 zapytania jednocześnie, a wszystkie Twoje klucze LiteLLM w organizacji mogą łącznie wysłać najwyżej 60 zapytań na minutę, chyba że Twoja instalacja ustala inne wartości.

Czego klucze nie mogą#

Klucze AITEZA, niezależnie od dostępu, mają następujące ograniczenia:

• Brak administracji. Klucz nie może korzystać z administracji organizacji (/api/admin/…), administracji platformy (/api/platform/…) ani niektórych innych funkcji administracyjnych. Twoje role administracyjne (Administrator organizacji, Administrator przestrzeni danych, administrator platformy) i Twoje uprawnienia administracyjne nie obowiązują w zapytaniach wysłanych kluczem.
• Brak zarządzania kluczami. Klucz nie może tworzyć, wyświetlać ani unieważniać kluczy API. Kluczami zarządzasz tylko na stronie Klucze API.
• Brak przepływów pracy. Przepływów pracy (workflows) nie można uruchomić kluczem, ani bezpośrednio, ani przez wiadomość na czacie. Uruchamiaj je w AITEZA po zalogowaniu.
• Klucze do odczytu nie zapisują. Klucz z dostępem Odczyt przyjmuje tylko GET, HEAD i OPTIONS. Każda inna metoda jest odrzucana, a klucz nie może niczego utworzyć, nawet czatu.
• Jedna organizacja. Klucz działa tylko w organizacji, w której go utworzono. Niezależnie od organizacji ma dostęp tylko do Twoich własnych czatów i plików (zobacz API AITEZA).
• Najwyżej 60 zapytań na minutę. Kolejne zapytania są odrzucane, dopóki nie upłynie czas podany w nagłówku Retry-After. Twoja instalacja może ustalić inną liczbę.

Klucze LiteLLM mogą wywoływać tylko endpointy modeli i tylko z Twoimi modelami (zobacz Wywoływanie modeli kluczem LiteLLM).

Kiedy klucz przestaje działać#

• Wygasa po upływie ważności.
• Zostaje unieważniony przez Ciebie lub administratora organizacji.
• Administrator organizacji wylogowuje Cię wszędzie, wyłącza Twoje konto lub odbiera Ci rolę Klucze API. Unieważnia to wszystkie Twoje klucze we wszystkich organizacjach. Usunięcie Cię z organizacji unieważnia Twoje klucze w tej organizacji.
• Tracisz dostęp w inny sposób, np. gdy bezpośrednio w systemie zarządzania tożsamością (Keycloak) Twojej instalacji Twoje konto zostaje wyłączone, rola zostaje Ci odebrana lub opuszczasz organizację. Twoje klucze są wtedy odrzucane w ciągu około minuty i unieważniane w ciągu 15 minut.
• Operatorzy Twojej instalacji wyłączają klucze API. Klucze, które nie zostały unieważnione ani nie wygasły, znów działają po ponownym włączeniu kluczy API.

Unieważnione klucze pozostają unieważnione: odzyskanie dostępu nie przywraca starych kluczy, więc utwórz nowe. Zresetowanie hasła nie unieważnia Twoich kluczy.

Unieważnianie klucza#

Programy używające tego klucza natychmiast tracą dostęp. Tego nie można cofnąć. Klucz przechodzi do sekcji Wygasłe lub unieważnione i pozostaje tam widoczny przez 30 dni. Unieważniony klucz LiteLLM jest też usuwany w LiteLLM.

Twoje klucze mogą unieważnić także administratorzy organizacji (zobacz Unieważnianie kluczy innych osób).

Komunikaty o błędach#

Gdy AITEZA odrzuca zapytanie wysłane kluczem AITEZA, odpowiada statusem HTTP i treścią JSON z kodem i krótkim komunikatem, np.:

Pozostałe odpowiedzi znaczą to samo co w samej AITEZA, np. 404 dla czegoś, co nie istnieje.

Na zapytania wysłane kluczem LiteLLM pod adres /v1 odpowiedzi przychodzą w formacie błędów API OpenAI, z wyjaśnieniem w polu error.message:

Gdy Twoje klucze LiteLLM wyczerpią miesięczny limit, LiteLLM sam odrzuca kolejne zapytania ze statusem 400 i komunikatem o przekroczonym budżecie, dopóki limit nie zacznie się od nowa na początku następnego miesiąca. LiteLLM odrzuca też zapytania ponad limity zapytań jednoczesnych i zapytań na minutę.