Klucze API — jak dać programowi klienta dostęp do publicznego API

Po co klucz API

Klucz API to dostęp dla programu, który nie jest częścią Noxti — sklepu klienta, jego ERP, hurtowni. Program łączy się z publicznym API (https://api.noxti.com/v1, opis na stronie Dokumentacja API, link w nagłówku zakładki) i może robić tylko to, na co pozwala rola, którą wybierzesz dla klucza. Roli administratora firmy klucz nie dostanie nigdy.

To coś innego niż konto techniczne dla n8n albo WAPRO na zakładce Dostęp dla programów (API) (konta techniczne — pomoc administratora firmy): klucz działa wyłącznie w publicznym API i ma własną rolę. Publiczne API to płatny dodatek do pakietu.

Gdzie i kto

Ustawienia → System → Klucze API. Zakładkę widzi tylko administrator firmy (Administrator firmy i superadministrator — kto co omija). Każde utworzenie, zmiana, nowy sekret, unieważnienie sekretu i wyłączenie klucza prosi o świeże potwierdzenie 2FA (Uwierzytelnianie dwuskładnikowe (2FA) — włączenie, kody zapasowe, wyłączenie).

Nad tabelą widać licznik Aktywne klucze: X z Y. Każdy klucz ma swój wiersz: nazwę, środowisko (Produkcja albo Test), rolę, początek sekretu, ostatnie użycie i status.

Nowy klucz

1. Kliknij Nowy klucz.
2. Nazwa — po niej poznasz, który program używa klucza („Sklep B2B”, „ERP klienta”). Dwa aktywne klucze nie mogą mieć tej samej nazwy. Nazwy później nie zmienisz.
3. Rola — klucz może tylko to, na co pozwala ta rola. Najlepiej załóż dla programu osobną rolę z samymi potrzebnymi uprawnieniami (Tworzenie i edycja roli — okno z dwiema zakładkami).
4. Dozwolone adresy IP (opcjonalnie) — gdy wpiszesz adresy, klucz zadziała tylko z nich. Możesz wpisać pojedynczy adres albo zakres, najwyżej 50 pozycji. Wklejona lista (oddzielona spacjami albo przecinkami) sama rozdzieli się na pozycje. Puste pole = klucz działa z każdego adresu.
5. Utwórz klucz — pokaże się sekret klucza, tylko ten jeden raz. Skopiuj go i przekaż do programu klienta, zanim zamkniesz okno; okno nie zamknie się, dopóki nie potwierdzisz, że sekret jest zapisany. Później widać już tylko jego początek.

Zmiana klucza

⋮ → Edytuj pozwala zmienić rolę, listę adresów IP i przełącznik Uruchamiaj automatyzacje dla zmian z tego klucza (czy zmiany zrobione przez program mają uruchamiać akcje automatyczne tak jak zmiany pracowników). Limity zapytań na minutę widzi i zmienia tylko obsługa Noxti.

Gdy rolę klucza ktoś później zamienił w rolę administratora, klucz ją zachowuje (i przestaje działać), dopóki nie wybierzesz innej roli.

Nowy sekret

Sekret ma datę ważności, tak jak tokeny kont technicznych. Przed jej upływem przypomnienie z linkiem do tej zakładki dostają osoby wskazane do przypomnień na zakładce Dostęp dla programów (API) (konta techniczne — pomoc administratora firmy) — gdy nikogo tam nie ma, nikt go nie dostanie. ⋮ → Nowy sekret wystawia nowy sekret (znów pokazany tylko raz). Stary sekret działa jeszcze przez krótki czas, żebyś zdążył wpisać nowy do programu; w rozwiniętym wierszu jest oznaczony jako Stary, kończy się. Ile godzin działa stary sekret, ustawiasz na zakładce Dostęp dla programów (API) w polu Jak długo działa stary klucz po wymianie (godz.) — tak samo jak dla tokenów kont technicznych.

Tego samego przycisku użyj, gdy:

• zgubiłeś sekret — wystaw nowy, a stary unieważnij (niżej);
• klucz ma status Brak sekretu.

Nie wystawiaj kolejnego nowego sekretu, zanim program nie przejdzie na ostatni — poprzedni przestanie wtedy działać od razu.

Unieważnienie sekretu (wyciek)

Rozwiń wiersz klucza strzałką z lewej: zobaczysz Sekrety tego klucza — początek, datę utworzenia, ostatnie użycie i koniec ważności. Przy sekrecie kliknij Unieważnij. Program, który go używa, od razu dostaje błąd; pozostałe sekrety klucza działają dalej. Tak zatrzymasz sekret, który wyciekł, albo stary sekret przed końcem jego okresu przejściowego.

Wyłączenie klucza

⋮ → Wyłącz klucz — gdy klient przestaje korzystać z API albo klucz nie jest już potrzebny.

• Program klienta od razu dostaje błąd 401; wszystkie sekrety klucza przestają działać.
• Tego nie da się cofnąć. Klucz zostaje na liście jako wyłączony, ale nie da się go włączyć z powrotem — w razie potrzeby utwórz nowy.
• Wyłączony klucz zwalnia miejsce w limicie, a jego nazwa jest znów wolna.

Limit kluczy

Firma może mieć tyle aktywnych kluczy, ile pozwala jej pakiet (licznik nad tabelą). Wyłączone klucze się nie liczą. Gdy limit jest pełny, Nowy klucz jest wyszarzony — wyłącz klucz, którego nikt już nie używa, albo poproś o wyższy limit.

Klucze ze statusem Inne środowisko nadal zajmują miejsce w limicie. Najpierw je wyłącz, potem utwórz nowe.

Gdy firma nie ma dodatku

Bez dodatku publicznego API zakładka pokazuje żółtą ramkę Twój pakiet nie zawiera publicznego API. Nowych kluczy nie utworzysz, a istniejących nie zmienisz ani nie dasz im nowego sekretu — programy klientów i tak nie mogą się nimi łączyć. Możesz za to posprzątać: przejrzeć klucze, unieważnić sekrety i wyłączyć klucze. Żeby dostać publiczne API, napisz do nas.

Gdy coś nie działa

• Przycisk Nowy klucz jest wyszarzony — pełny limit albo brak dodatku; najedź na przycisk, żeby zobaczyć powód.
• „Aktywny klucz o tej nazwie już istnieje.” — wybierz inną nazwę albo najpierw wyłącz stary klucz o tej nazwie.
• Program dostaje błąd 401 — sekret unieważniony, wygasły albo klucz wyłączony; sprawdź też, czy program łączy się z adresu z listy dozwolonych adresów IP.
• Program dostaje błąd 403 — rola klucza nie pozwala na tę operację. Zmień uprawnienia roli albo wybierz kluczowi inną rolę.
• Nie widzę zakładki — nie jesteś administratorem firmy.