Wirtualne klucze AI Gateway (Virtual Key)
Wirtualny klucz (Virtual Key) to uprawnienie wydawane przez AI Gateway, służące do autoryzowanego dostępu do punktów końcowych proxy. Wydajesz wirtualne klucze swoim aplikacjom i narzędziom AI, natomiast prawdziwe klucze API dostawcy pozostają bezpieczne po stronie gateway’a. Dzięki temu prawdziwe klucze nie są rozprzestrzeniane, a każdy wirtualny klucz można osobno ograniczać uprawnieniami, prędkością, rotować i odwoływać. W tym dokumencie opisano pełny cykl życia wirtualnego klucza.
Dlaczego warto używać wirtualnych kluczy
- Ochrona prawdziwych kluczy — Aplikacje i narzędzia używają wyłącznie wirtualnych kluczy, prawdziwy klucz API dostawcy nie jest ujawniany.
- Granularne uprawnienia — Możesz tworzyć różne wirtualne klucze dla różnych projektów lub narzędzi, osobno limitując dostępne modele, kanały i limity prędkości.
- Możliwość natychmiastowego odwołania — Jeśli klucz wycieknie lub nie jest już potrzebny, możesz go natychmiast odwołać lub zrotować bez wpływu na inne klucze.
Wymagania wstępne
- Musisz być zalogowany na konto ServBay.
- Musisz dodać przynajmniej jeden kanał na stronie Kanały.
Tworzenie wirtualnego klucza
Wejdź w AI Gateway → Klucze (Keys) i kliknij Utwórz (Create):
- Nazwa — Służy do identyfikacji celu klucza (np.
claude-code,my-app-dev). - Opis (opcjonalnie) — Dodatkowe informacje.
- Data wygaśnięcia — Możesz ustawić brak limitu lub konkretną datę.
- Dozwolone kanały (opcjonalnie) — Wybierz z etykiet, by ograniczyć kanały, do których może być wykorzystany klucz. Pozostaw puste, by nie nakładać ograniczeń.
- Dozwolone modele (opcjonalnie) — Wybierz, które modele można używać z tym kluczem. Pozostaw puste, by nie ograniczać.
- Limity prędkości (opcjonalnie):
- RPM / TPM — Maksymalna liczba zapytań lub tokenów na minutę.
- RPD / TPD — Maksymalna liczba zapytań lub tokenów na dzień.
Klucz w postaci jawnej wyświetlany tylko raz
Po utworzeniu klucza, Gateway pokaże klucz w postaci jawnej tylko raz (np. servbay-sk-xxxxxxxx...). Natychmiast go skopiuj i zapisz – po zamknięciu okna gateway zachowuje tylko prefiks do identyfikacji i nie możesz ponownie wyświetlić pełnego klucza. Jeśli zgubisz klucz, musisz wygenerować nowy poprzez "Rotację".
Lista kluczy
Lista pokazuje dla każdego wirtualnego klucza:
- Prefiks — np.
servbay-sk-abcd...do identyfikacji. - Status — aktywny (active), odwołany (revoked), wygasły (expired).
- Data utworzenia / ostatniego użycia
- Etykiety uprawnień — dozwolone modele/kanały, limity prędkości.
Zarządzanie kluczami
Dla każdego klucza na liście możesz wykonać następujące akcje:
| Akcja | Opis | Efekt |
|---|---|---|
| Edytuj (Edit) | Zmień nazwę, opis, dozwolone modele/kanały, limity prędkości | Skutkuje natychmiast, sam klucz się nie zmienia |
| Rotuj (Renew) | Wygeneruj nowy klucz jawny, stary klucz przestaje działać natychmiast, nowy widoczny raz | Musisz podmienić klucz we wszystkich używających go aplikacjach |
| Odwołaj (Revoke) | Natychmiast blokuje klucz, ale zachowuje ślad audytowy | Nieodwracalne; zapytania z tym kluczem będą odrzucane |
| Usuń (Delete) | Całkowicie usuwa klucz | Nieodwracalne |
Rotacja vs Odwołanie
- Rotacja (Renew): Klucz pozostaje, ale zmienia się wartość jawna — do scenariuszy, gdy podejrzewasz wyciek, ale chcesz używać tej samej konfiguracji. Pamiętaj o aktualizacji klucza we wszystkich aplikacjach.
- Odwołanie (Revoke): Klucz traci ważność na zawsze, ale ślad audytowy pozostaje — dobre, gdy klucz nie jest już potrzebny. Obie operacje wymagają potwierdzenia.
Związek z funkcją "Jedno kliknięcie na przejęcie"
Kiedy używasz Jednoklikowego przejęcia, by skierować narzędzie AI na Gateway, system automatycznie tworzy dedykowany wirtualny klucz i wpisuje go do konfiguracji narzędzia. Możesz również ręcznie zarządzać tymi automatycznie stworzonymi kluczami na stronie Klucze.
Najczęściej zadawane pytania (FAQ)
- Q: Co zrobić, jeśli zapomniałem skopiować klucz w postaci jawnej?
- A: Nie ma ponownej możliwości podglądu klucza. Wykonaj "Rotację", by wygenerować nowy i zamień klucz w aplikacji.
- Q: Czym różni się odwołanie od usunięcia klucza?
- A: Odwołanie zachowuje wpis klucza (przydatne do audytu), usunięcie trwale go kasuje. Obydwie operacje sprawiają, że klucz jest natychmiast nieważny.
- Q: Co się stanie, jeśli ograniczę dozwolone modele, a aplikacja zażąda innego modelu?
- A: Gateway odrzuci żądania spoza listy uprawnień dla danego klucza. Upewnij się, że żądane modele są na liście lub zdejmij ograniczenia.
- Q: Jak działa limit prędkości?
- A: Przekroczenie limitu RPM/TPM/RPD/TPD spowoduje, że gateway zablokuje nadprogramowe zapytania. Po przeglądzie zużycia na stronie Statystyki możesz dostosować limity.
Podsumowanie
Wirtualne klucze pozwalają bezpiecznie i z minimalnymi uprawnieniami przekazywać zdolności AI do aplikacji i narzędzi. Dzięki możliwości ograniczania modeli/kanałów oraz ustawiania limitów prędkości możesz dokładnie dopasować uprawnienia do każdego scenariusza użycia, a w razie potrzeby natychmiast rotować lub odwoływać klucz — bez ingerencji w prawdziwy klucz API dostawcy.
