Uwierzytelnianie
Klucze API i bezpieczne uwierzytelnianie żądań.
Dostęp do API zabezpieczony jest kluczami przekazywanymi w nagłówku Authorization. Opisujemy tu generowanie, rotację i ograniczanie zakresu kluczy oraz dobre praktyki ich przechowywania.
Generowanie klucza
Klucze API tworzysz w panelu organizacji. Każdy klucz jest przypisany do konkretnego projektu i dziedziczy jego uprawnienia.
Otwórz ustawienia API
Przejdź do Ustawienia → Klucze API w panelu projektu.
Utwórz nowy klucz
Kliknij Nowy klucz, nadaj mu czytelną nazwę (np. produkcja-backend) i wybierz zakres uprawnień.
Skopiuj sekret
Pełna wartość klucza jest pokazywana tylko raz. Zapisz ją w bezpiecznym miejscu, zanim zamkniesz okno.
Bez ponownego podglądu: Po zamknięciu okna RAGGY przechowuje wyłącznie skrót klucza. Jeśli go zgubisz, wygeneruj nowy i wycofaj poprzedni.
Użycie w nagłówku
Klucz przekazujesz w nagłówku Authorization ze schematem Bearer. Każde żądanie do API musi zawierać ten nagłówek.
curl https://api.raggy.pl/v1/collections \
-H "Authorization: Bearer rg_live_3f9c2a7e8b1d4f60a5c9e2b7d8f1a4c6"Żądania bez poprawnego nagłówka zwracają 401 Unauthorized. Szczegóły punktów końcowych znajdziesz w sekcji API.
Prefiksy i typy kluczy
Prefiks klucza wskazuje jego środowisko. Dzięki temu od razu widać, czy żądanie trafia do danych produkcyjnych, czy testowych.
| Prefiks | Środowisko | Opis |
|---|---|---|
| rg_live_ | Produkcja | Operuje na danych produkcyjnych. Traktuj jak hasło. |
| rg_test_ | Testowe | Działa na izolowanych danych testowych — bezpieczny do eksperymentów. |
Używaj kluczy rg_test_ w środowiskach CI i lokalnych, a rg_live_ wyłącznie w produkcji.
Rotacja i zakres
Każdy klucz ma ograniczony zakres — zestaw uprawnień określający, co może robić. Nadawaj możliwie najwęższy zakres potrzebny do zadania.
- Odczyt — pobieranie kolekcji, źródeł i wyników wyszukiwania.
- Zapis — dodawanie i aktualizacja źródeł oraz indeksowanie.
- Rozmowa — odpytywanie modelu i prowadzenie konwersacji.
Klucze możesz w dowolnym momencie wycofać (revoke) lub rotować. Rotacja polega na wygenerowaniu nowego klucza, wdrożeniu go i dopiero potem wycofaniu starego.
Dobre praktyki
Nie commituj kluczy: Nigdy nie umieszczaj kluczy w repozytorium ani w kodzie frontendu. Przechowuj je w zmiennych środowiskowych lub menedżerze sekretów.
- Przechowuj klucze w zmiennych środowiskowych (np.
RAGGY_API_KEY), nie w kodzie. - Stosuj osobne klucze dla każdej usługi i środowiska, aby ułatwić rotację.
- Wycofuj klucze natychmiast po podejrzeniu wycieku.
- Regularnie przeglądaj listę aktywnych kluczy i usuwaj nieużywane.
Zasada minimalnych uprawnień: Klucz tylko do odczytu nie może zmodyfikować danych — używaj go wszędzie, gdzie nie potrzebujesz zapisu.