Uwierzytelnianie - Omnilinker

Każde wywołanie API Omnilinkera zawiera klucz API. Klucz działa w imieniu osoby, która go utworzyła, tylko w zakresie nadanego mu dostępu i zawsze wyłącznie w organizacji tej osoby. Nie ma osobnego logowania ani tokenu do odświeżania: wysyłasz klucz z każdym żądaniem.

Wysyłanie klucza

Umieść klucz w nagłówku X-Api-Key:

curl https://omnilinker.pl/api/api-key-management/whoami \
  -H "X-Api-Key: $OMNILINKER_API_KEY"

$headers = @{ "X-Api-Key" = $env:OMNILINKER_API_KEY }
Invoke-RestMethod https://omnilinker.pl/api/api-key-management/whoami -Headers $headers

import os, requests

r = requests.get("https://omnilinker.pl/api/api-key-management/whoami",
                 headers={"X-Api-Key": os.environ["OMNILINKER_API_KEY"]})
print(r.json())

Omnilinker przyjmuje też nagłówek o nazwie Api-Key. Nigdy nie odczytuje klucza z adresu URL: klucz w parametrach zapytania jest pomijany, a żądanie traktowane jak żądanie bez klucza. Adresy URL trafiają do logów serwerów i proxy, więc trzymaj klucze w nagłówkach. Klucze zaczynają się od olk_, dzięki czemu klucz, który wyciekł, łatwo zauważyć w logach i skanerach sekretów. Klucze utworzone, zanim wprowadzono ten prefiks, go nie mają i nadal działają.

Jak zdobyć klucz

Otwórz Klucze API

W Omnilinkerze otwórz Klucze API z menu głównego (otwiera Ustawienia > Integracje > Klucze API). Potrzebujesz uprawnień Klucze API i Tworzenie kluczy API w grupie Klucze API.

Zacznij nowy klucz

Kliknij Nowy klucz API. W sekcji Co będzie z niego korzystać? wybierz szablon najbliższy Twojej integracji; zobacz Szablony. Klucz startuje z dostępem z tego szablonu, ograniczonym do tego, co sam możesz.

Nazwij go i wybierz, kiedy wygaśnie

W polu Nazwa wpisz, gdzie działa klucz, od 3 do 64 znaków, na przykład system i zadanie. W polu Wygasa wybierz 30 dni, 90 dni (domyślnie), 1 rok, Wybierz datę albo Nigdy. Opcjonalnie wypełnij pole Notatki, na przykład tym, kto odpowiada za integrację.

W razie potrzeby dostosuj dostęp

W sekcji Co może robić kliknij Dostosuj dostęp…, aby dodać lub usunąć uprawnienia, a potem kliknij Zastosuj.

Utwórz klucz i skopiuj go

Kliknij Utwórz klucz. Klucz pojawia się raz, w polu Twój klucz API: kliknij Kopiuj i zapisz go w menedżerze sekretów. Omnilinker przechowuje tylko jego skrót, więc nie pokaże go ponownie. Jeśli go zgubisz, wymień klucz, aby dostać nowy.

Przetestuj go

Kliknij Przetestuj klucz. Omnilinker wywołuje API nowym kluczem z Twojej przeglądarki i pokazuje Test udany wraz z użytkownikiem, w którego imieniu działa klucz, i liczbą jego uprawnień. Następnie zaznacz Zapisałem klucz w bezpiecznym miejscu i kliknij Gotowe.

Tworzenie, wymianę i unieważnianie kluczy szczegółowo opisuje strona Klucze API.

Sprawdzanie klucza z kodu

GET /api/api-key-management/whoami zwraca dane samego klucza. Nie wymaga żadnego uprawnienia, więc może go wywołać każdy ważny klucz. Niech to będzie pierwsze wywołanie nowej integracji albo jej test działania:

{
  "apiKeyId": "<key-id>",
  "name": "Power BI — raport cen",
  "displayPrefix": "olk_<prefix>",
  "purpose": "Integration",
  "userId": "<user-id>",
  "userName": "<owner-user-name>",
  "tenantId": "<organization-id>",
  "tenantName": "<organization-name>",
  "expirationTime": "2027-01-11T09:30:00Z",
  "grantedPermissions": [
    "Ordering.Orders",
    "Ordering.Journal"
  ]
}

grantedPermissions wymienia, co klucz faktycznie może w tej chwili: jego własne uprawnienia, przycięte do tego, co nadal ma jego właściciel, i do tego, co klucze w ogóle mogą mieć. expirationTime ma wartość null dla klucza, który nie wygasa.

Co może klucz

Dostęp klucza to część wspólna dwóch rzeczy:

Uprawnień samego klucza, wybranych przy tworzeniu albo później przez Zmień dostęp.
Uprawnień jego właściciela. Klucz nigdy nie może więcej niż osoba, która go utworzyła. Jeśli ta osoba straci uprawnienie, klucz też je straci.

Klucz przestaje działać, a każde wywołanie z nim zwraca 401 Unauthorized, gdy:

wygaśnie,
ktoś go dezaktywuje albo usunie,
został wymieniony, a okres działania starego klucza się skończył,
jego właściciel zostanie dezaktywowany, zablokowany albo usunięty.

Czego klucz nigdy nie może

Niektóre uprawnienia nigdy nie są dostępne dla klucza, niezależnie od jego ustawień. W panelu dostępu są w sekcji Nie dla kluczy API: „Klucz nie może zarządzać użytkownikami, kluczami ani ustawieniami, więc wyciek klucza nie odetnie Ci dostępu.”. Należą do nich:

zarządzanie użytkownikami, rolami, organizacjami, funkcjami, ustawieniami i kluczami API;
zarządzanie kontami marketplace i kontami kurierskimi, które przechowują Twoje dane logowania do tych usług;
tworzenie i zmiana reguł automatyzacji i własnych wyzwalaczy, uruchamianie własnego wyzwalacza poza dozwolonymi statusami i zmiana ustawień automatyzacji;
zmiana właściciela tożsamości produktów lub stanów magazynu, generowanie kluczy agenta ERP i wybór użytkownika ERP, którym Omnilinker zapisuje dane.

Inne uprawnienia mają sens tylko na ekranie, na przykład zapisane filtry, pulpity i strony ustawień. Klucze też nie mogą z nich korzystać. Aby zobaczyć je w panelu dostępu, włącz Pokaż uprawnienia tylko dla ekranu. Wszystko w Centrum powiadomień działa tylko na ekranie. Endpoint, który wymaga zalogowanej osoby, ale żadnego konkretnego uprawnienia, odmawia kluczom kodem 403 Forbidden. Wyjątkiem jest whoami.

Szablony

Szablon	Dla	Dostęp na start
Raporty i BI	Power BI, Excel, Looker Studio	Odczytuje katalog, ceny, oferty, zamówienia i stany. Oznaczony TYLKO ODCZYT.
Synchronizacja katalogu i cen	PIM lub sklep, który wysyła produkty i ceny	Tworzy i aktualizuje produkty, marki, kategorie, tagi i poziomy cen. Nigdy nie usuwa.
Integracja zamówień	n8n, Make lub własny middleware	Tworzy i aktualizuje zamówienia i ustawia ich status, odczytuje statusy i źródła zamówień oraz dziennik zamówień, odczytuje przesyłki, pobiera etykiety i odczytuje kontakty.
Własny	Wszystko inne	Bez dostępu. Każde uprawnienie wybierasz sam.

Szablon nadaje tylko te uprawnienia, które sam masz; pozostałe pomija. Żaden szablon nie zawiera uprawnienia Podgląd danych osobowych w grupie Zamówienia. Bez niego dane osobowe kupującego w zamówieniach wracają zamaskowane, a zmiana kupującego, adresu dostawy, danych do faktury lub punktu odbioru w istniejącym zamówieniu jest odrzucana. Jeśli Twoja integracja odczytuje lub zmienia nazwiska, adresy lub dane kontaktowe kupujących, dodaj to uprawnienie przez Dostosuj dostęp…. Panel dostępu ostrzeże wtedy: „Ten klucz może teraz usuwać dane lub widzieć dane osobowe.”.

Bezpieczeństwo kluczy

Jeden klucz na integrację. Jeśli jeden system zostanie przejęty, unieważniasz jeden klucz, a reszta działa dalej. Nazwa jest unikalna dla każdej osoby, co pomaga odróżniać klucze.
Przechowuj klucz jako sekret, w zmiennej środowiskowej lub menedżerze sekretów, nigdy w kodzie źródłowym ani w kodzie działającym w przeglądarce.
Nadawaj jak najmniejszy dostęp. Zacznij od najbliższego szablonu i usuń to, czego integracja nie używa.
Pozwól mu wygasnąć. Wybieraj Nigdy tylko dla klucza, którego ktoś pilnuje. Omnilinker wysyła właścicielowi powiadomienie 7 dni przed wygaśnięciem klucza: „Wymień go wcześniej, inaczej to, co z niego korzysta, przestanie działać.”.
Wymieniaj zamiast tworzyć od nowa. Wymień klucz… daje nowy klucz z tą samą nazwą, notatkami i dostępem, a stary działa jeszcze przez czas, który wybierzesz w polu Stary klucz ma działać jeszcze przez: Zatrzymaj od razu, 1 godzinę, 24 godziny albo 7 dni. W tym czasie przełącz swój system na nowy klucz.
Pilnuj nieużywanych kluczy. Lista pokazuje, kiedy każdy klucz był ostatnio użyty (z dokładnością do kilku minut), i ma filtr Nieużywane 30+ dni. Dezaktywuj to, czego nikt nie używa.

Inne sposoby logowania

Ludzie logują się do aplikacji webowej nazwą użytkownika i hasłem; to logowanie nie jest dla programów. W Omnilinkerze nie zarejestrujesz własnego klienta OAuth ani OpenID Connect, więc do każdej integracji używaj klucza API. Agenci ERP i stacje etykiet też używają kluczy API, ale dostają je tam, gdzie są podłączane: w połączeniu z ERP i w Urządzenia > Stanowiska. Te klucze widać na stronie Klucze API w grupie Agenci i urządzenia i zarządza się nimi tam, gdzie urządzenie jest podłączone. Zobacz Instalacja agenta ERP Sync i Instalacja aplikacji Omnilinker Station.

Rozwiązywanie problemów

401 Unauthorized przy każdym wywołaniu

Sprawdź, czy nagłówek to X-Api-Key (lub Api-Key) i czy wartość to cały klucz, zaczynający się od olk_. Klucz w adresie URL jest pomijany.
Sprawdź, czy klucz jest nadal aktywny: na stronie Klucze API klucz, który przestał działać, ma status Wygasł, Nieaktywny albo Zastąpiony.
Sprawdź, czy osoba, która utworzyła klucz, nadal może się zalogować. Klucz przestaje działać, gdy jego właściciel zostanie dezaktywowany, zablokowany albo usunięty.

403 Forbidden na jednym endpoincie

Wywołaj whoami i poszukaj uprawnienia w grantedPermissions. Jeśli go brakuje, dodaj je przez Zmień dostęp albo poproś właściciela klucza: tylko właściciel może zmienić dostęp klucza i potrzebuje do tego uprawnienia Zmiana dostępu kluczy API.
Jeśli właściciel stracił uprawnienie, klucz też je stracił. Poproś administratora, aby przywrócił je właścicielowi.
Endpoint może wymagać uprawnienia, którego klucze nigdy nie dostają, albo nie wymagać żadnego; zobacz sekcję „Czego klucz nigdy nie może” wyżej.
Moduł może nie być włączony dla Twojej organizacji; zobacz Moduły i dostępność funkcji.

Test nieudany przy tworzeniu klucza

„Test nieudany” z kodem statusu oznacza, że API nie przyjęło klucza. Odczekaj chwilę i kliknij Testuj ponownie; jeśli dalej się nie uda, skontaktuj się z pomocą. „Nie udało się połączyć z API” oznacza, że żądanie nie dostało odpowiedzi, co nie mówi nic o kluczu: sprawdź połączenie i przetestuj ponownie.

Zgubiłem klucz

Omnilinker nie pokaże klucza ponownie. Otwórz menu klucza i kliknij Wymień klucz…, aby dostać nowy z tym samym dostępem, a potem zaktualizuj swój system. Wymiana wymaga uprawnienia Edycja i wymiana kluczy API.

Klucze API

Tworzenie, edycja, wymiana i unieważnianie kluczy.

Przegląd dla programistów

Konwencje, stronicowanie i błędy.

Lista uprawnień

Co pozwala zrobić każde uprawnienie.

Webhooki i kanały zmian

Śledzenie zmian w zamówieniach przez dziennik zamówień.

​Wysyłanie klucza

​Jak zdobyć klucz

​Sprawdzanie klucza z kodu

​Co może klucz

​Czego klucz nigdy nie może

​Szablony

​Bezpieczeństwo kluczy

​Inne sposoby logowania

​Rozwiązywanie problemów