Uwierzytelnianie
Format klucza, gdzie go trzymać, ograniczenia dla pojedynczych kluczy, rotacja i co zrobić po wycieku.
Każde zapytanie do API niesie jeden klucz API w nagłówku Authorization:
Authorization: Bearer sk-popnow-3f9c0a…Innej metody nie ma: klucze w query stringu adresu URL nigdy nie są akceptowane, a logowanie na popnow.ai nie działa w API.
Jeden wyjątek: trasy zgodne z OpenAI pod /v1 odczytują klucz także z nagłówka x-api-key, więc klienty w stylu OpenAI działają bez zmian. Natywne trasy /api/v1 czytają tylko Authorization.
Jak wygląda klucz
Klucz to sk-popnow- i 48 małych znaków szesnastkowych. Po utworzeniu konsola API pokazuje tylko kilka pierwszych znaków, więc zgubionego klucza nie da się odzyskać — po prostu utwórz nowy.
Utwórz klucz
- Zaloguj się na popnow.ai i otwórz konsolę API.
- Wybierz Create key i nadaj nazwę, która mówi, gdzie klucz będzie działał, np.
production-backend. - Od razu go skopiuj. Wyświetla się tylko raz.
Możesz mieć kilka kluczy jednocześnie. Osobny dla każdego środowiska lub usługi to dobry nawyk — wtedy można cofnąć jeden, nie ruszając pozostałych. Wszystkie korzystają z tego samego salda kredytów.
Gdzie go trzymać
- W zmiennej środowiskowej albo w magazynie sekretów twojej platformy (
POPNOW_API_KEY), a nie w kodzie źródłowym. - Nigdy w przeglądarce, aplikacji mobilnej ani w żadnym kodzie działającym na cudzym urządzeniu. Kto może odczytać klucz, może wydawać twoje kredyty. Postaw pośrodku własny serwer i niech to on wywołuje PopNow.
- Nie w logach. Jeśli logujesz nagłówki zapytań, najpierw usuń
Authorization.
Co wolno kluczowi
Każdy klucz może mieć własne ograniczenia, ustawiane w konsoli API:
| Ograniczenie | Działanie | Błąd, gdy blokuje |
|---|---|---|
| Dozwolone modele | Klucz może wywoływać tylko wymienione modele | 40301 |
| Lista dozwolonych IP | Zapytania muszą przychodzić z tych adresów lub zakresów | 40302 |
| Limity wydatków | Dzienny, miesięczny i całkowity limit dla tego klucza, w kredytach | 40202 |
Domyślnie klucz nie ma ani ograniczeń, ani limitów. Kluczom produkcyjnym daj najwęższy zakres, który wystarcza.
Zadania należą do klucza, który je utworzył
recordInfo, retry, purge, lista zadań i zużycie widzą tylko zadania utworzone tym samym kluczem. Zadanie utworzone innym kluczem z twojego konta odpowiada 404 — dokładnie tak jak zadanie, które nie istnieje. Generacji uruchomionych na stronie nie widzi żaden klucz. Pełny obraz konta daje konsola API.
Rotacja
Jak wymienić klucz bez przestoju:
- Utwórz nowy klucz.
- Wdróż go wszędzie, gdzie używany był stary.
- Sprawdź w konsoli, że czas ostatniego użycia starego klucza przestał się zmieniać.
- Cofnij stary klucz.
Gdy klucz wycieknie
- Cofnij go od razu w konsoli API. Działa od następnego zapytania.
- Utwórz zastępczy i wdróż go.
- Sprawdź, do czego był używany: logi i zużycie w konsoli pokazują każde zadanie utworzone tym kluczem.
- Ogranicz nowy klucz listą dozwolonych IP i limitem wydatków.
Jeśli widzisz wydatki, których nie robiłeś, napisz do pomocy.
Jak wygląda błąd
Wszystkie trzy problemy z uwierzytelnianiem zwracają HTTP 401 z code: 401; rozróżnia je msg:
Co mówi msg | Co się stało | Co zrobić |
|---|---|---|
| Brak danych uwierzytelniających | Nie dotarł nagłówek Authorization | Sprawdź, czy nagłówek jest ustawiony i czy działający proces wczytał zmienną środowiskową |
| Nierozpoznany format klucza | Coś dotarło, ale to nie jest klucz PopNow | Upewnij się, że zaczyna się od sk-popnow-; być może wklejono coś innego |
| Nieprawidłowe lub wygasłe dane | Klucz nie istnieje, został cofnięty albo wygasł | Utwórz nowy klucz; ponawianie nigdy nie zadziała |
Ważny klucz też może dostać 403 — na przykład gdy adres e-mail konta nie jest jeszcze potwierdzony (40310). Zobacz Błędy.