Wirtualne klucze bramy AI (Virtual Key)
Wirtualny klucz (Virtual Key) to poświadczenie wydawane przez bramę AI, które służy do uzyskiwania dostępu do punktów końcowych proxy bramy. Wirtualne klucze przekazujesz aplikacjom i narzędziom AI, natomiast prawdziwe klucze API dostawcy pozostają wyłącznie po stronie bramy. Dzięki temu unikasz rozproszenia prawdziwych kluczy, a jednocześnie możesz dla każdego wirtualnego klucza osobno ograniczać uprawnienia i szybkość, a także go rotować i unieważniać. W tym artykule opisujemy pełne zarządzanie cyklem życia wirtualnych kluczy.
Dlaczego warto używać wirtualnych kluczy
- Ochrona prawdziwych kluczy — aplikacje i narzędzia mają styczność wyłącznie z wirtualnymi kluczami, a prawdziwy klucz dostawcy nie wycieka.
- Uprawnienia dopasowane do zastosowania — możesz utworzyć osobny wirtualny klucz dla każdego projektu lub narzędzia i w każdym niezależnie ograniczyć dostępne modele, kanały oraz szybkość.
- Możliwość odebrania w każdej chwili — gdy klucz wycieknie lub przestanie być potrzebny, wystarczy go unieważnić lub zrotować, bez wpływu na pozostałe klucze.
Wymagania wstępne
- Zalogowane konto ServBay.
- Co najmniej jeden działający kanał dodany na stronie Kanały.
Tworzenie wirtualnego klucza
Przejdź do strony Brama AI → Klucze (Keys) i kliknij Utwórz (Create):
- Nazwa — służy do rozpoznania przeznaczenia klucza (np.
claude-code,my-app-dev). - Opis (opcjonalnie) — dodatkowe informacje.
- Czas wygaśnięcia — możesz ustawić brak terminu ważności lub konkretną datę.
- Dozwolone kanały (opcjonalnie) — wielokrotny wybór tagów ogranicza routing klucza wyłącznie do wskazanych kanałów; pozostawienie pola pustego oznacza brak ograniczeń.
- Dozwolone modele (opcjonalnie) — ogranicza klucz do wywoływania wyłącznie wskazanych modeli; pozostawienie pola pustego oznacza brak ograniczeń.
- Limity szybkości (opcjonalnie):
- RPM / TPM — maksymalna liczba żądań / tokenów na minutę.
- RPD / TPD — maksymalna liczba żądań / tokenów na dzień.
Tekst jawny można w każdej chwili odzyskać
Po pomyślnym utworzeniu klucza brama wyświetli klucz w postaci jawnej (w formacie servbay-sk-xxxxxxxx...). Brama przechowuje tekst jawny lokalnie, więc możesz go później odzyskać w szczegółach klucza. Jedynie historyczne klucze utworzone dawniej w formie skrótu (hash) nie mają możliwego do odzyskania tekstu jawnego (próba odzyskania zwraca 409). Jeśli podejrzewasz, że klucz wyciekł, po prostu wykonaj «rotację».
Lista kluczy
Lista kluczy pokazuje dla każdego wirtualnego klucza:
- Prefiks — np.
servbay-sk-abcd..., służy do identyfikacji. - Status — aktywny (active), unieważniony (revoked), wygasły (expired).
- Data utworzenia / data ostatniego użycia.
- Znaczniki uprawnień — dozwolone modele / kanały, limity szybkości.
Zarządzanie kluczami
Na liście kluczy możesz wykonać dla każdego klucza następujące operacje:
| Operacja | Opis | Efekt |
|---|---|---|
| Edytuj (Edit) | Zmiana nazwy, opisu, dozwolonych modeli / kanałów oraz limitów szybkości | Działa natychmiast, sam klucz się nie zmienia |
| Rotacja (Renew) | Ponowne wygenerowanie tekstu jawnego; stary tekst jawny natychmiast przestaje działać, a nowy możesz odzyskać w dowolnym momencie | Wymaga zaktualizowania wszystkich aplikacji i narzędzi korzystających z tego klucza |
| Unieważnienie (Revoke) | Natychmiast wyłącza klucz, ale zachowuje zapis do celów audytu | Nieodwracalne; żądania z tym kluczem będą odrzucane |
| Usuń (Delete) | Całkowite usunięcie klucza | Nieodwracalne |
Rotacja kontra unieważnienie
- Rotacja (Renew): klucz nadal istnieje, zmienia się jedynie jego tekst jawny — sprawdza się, gdy podejrzewasz wyciek klucza, ale chcesz dalej korzystać z tej samej konfiguracji; pamiętaj o zaktualizowaniu danych po stronie użytkowników.
- Unieważnienie (Revoke): trwale unieważnia klucz, ale zachowuje jego zapis na potrzeby audytu — sprawdza się, gdy masz pewność, że dany klucz nie jest już potrzebny. Zarówno rotacja, jak i unieważnienie wymagają dodatkowego potwierdzenia.
Związek z przejęciem jednym kliknięciem
Gdy za pomocą przejęcia jednym kliknięciem skierujesz narzędzie AI na bramę, brama automatycznie utworzy dla niego dedykowany wirtualny klucz i zapisze go w konfiguracji narzędzia. Tymi automatycznie utworzonymi kluczami możesz też zarządzać ręcznie na stronie kluczy.
Częste pytania (FAQ)
- P: Zapomniałem skopiować tekst jawny klucza. Co mam zrobić?
- O: Tekst jawny możesz odzyskać w szczegółach klucza. Jedynie historyczne klucze utworzone dawniej w formie skrótu nie dają się odzyskać — w takim przypadku wykonaj «rotację».
- P: Czym różni się unieważnienie od usunięcia?
- O: Unieważnienie zachowuje zapis klucza (na potrzeby audytu), natomiast usunięcie całkowicie go czyści. Oba działania natychmiast unieczynniają klucz.
- P: Co się stanie, gdy po ograniczeniu «dozwolonych modeli» aplikacja poprosi o inny model?
- O: Brama odrzuci żądania dotyczące modeli spoza uprawnień tego klucza. Upewnij się, że modele używane przez aplikację znajdują się na liście dozwolonych, albo zniesienie ograniczenie.
- P: Co się dzieje, gdy zostanie przekroczony limit szybkości?
- O: Żądania przekraczające RPM/TPM/RPD/TPD zostaną ograniczone przez bramę. Na stronie Statystyki możesz obserwować rzeczywiste zużycie i na tej podstawie dostosować limity.
Podsumowanie
Wirtualne klucze pozwalają udostępniać możliwości AI aplikacjom i narzędziom w sposób oparty na minimalnych uprawnieniach i możliwy do wycofania. W połączeniu z ograniczeniami dozwolonych modeli / kanałów oraz limitami szybkości możesz dopasować poświadczenia do każdego scenariusza użycia i w razie potrzeby w każdej chwili je zrotować lub unieważnić — bez sięgania do prawdziwego klucza API dostawcy.
