Przejdź do głównej zawartości

Klucze API (api_keys)

Klucze API z tokenem bearer o określonym zakresie, przeznaczone do integracji między systemami. Token w postaci jawnej jest pokazywany tylko raz, przy utworzeniu; przechowywany jest wyłącznie jego skrót SHA-256. Klucz może dodatkowo mieć powiązanie z dystrybutorem (organizacja, kanał sprzedaży i techniczne konto klienta) oraz opcjonalną datę ważności — staje się wtedy danymi uwierzytelniającymi partnera dla przestrzeni /api/v1/external/*, którą w pełni opisuje przewodnik integracyjny Partner API access.

API publiczne​

Metoda i ścieżkaKtoPrzeznaczenie
GET /api/v1/admin/api-keysadministratorLista kluczy z datą ostatniego użycia, powiązaniem i datą ważności
POST /api/v1/admin/api-keysadministratorUtworzenie; zwraca token bearer tylko raz
DELETE /api/v1/admin/api-keys/:idadministratorUnieważnienie

Wywołania z zewnątrz uwierzytelniają się nagłówkiem Authorization: Bearer sk_live_…. requireApiKey(scope) i requireBoundApiKey(scope) to pre-handlery Fastify, które moduł api_keys udostępnia jako porty (dlatego trasa innego modułu odpowiada 503 MODULE_DISABLED, gdy ten moduł jest wyłączony); trasy są nimi chronione (requireApiKey('catalog:write'), requireBoundApiKey('orders:write') itd.).

Wyliczenie zakresów​

Przy tworzeniu zakresy są sprawdzane względem typowanego katalogu w packages/contracts/src/api-keys.ts (apiKeyScopeSchema):

ZakresZnaczenie
catalog:readOdczyty PIM (klucz niepowiązany) i zewnętrzne API katalogu (klucz powiązany)
catalog:writeZapis PIM według SKU — tylko klucze niepowiązane
orders:readOdczyt zamówień przez zewnętrzne API — tylko klucze powiązane
orders:writePrzyjmowanie zamówień przez zewnętrzne API — tylko klucze powiązane
platform.api_description.readOpis API — GET /api/v1/_openapi.json i GET /api/v1/_docs

Egzekwowanie nadal sprawdza tylko obecność zakresu na liście, więc dawne, dowolnie zapisane zakresy w istniejących kluczach nadal są odczytywane i egzekwowane — walidacji podlega tylko tworzenie.

Klucz działa z zakresami, które otrzymał, dlatego administrator może utworzyć klucz tylko z zakresami, które ma jego własna rola; posiadacz symbolu wieloznacznego * może nadać dowolny zakres. integrations:manage otwiera ekran kluczy, ale sam nie daje catalog:write ani orders:*. Zakres, którego tworzący nie ma, jest odrzucany z 403 API_KEY_SCOPE_NOT_HELD, a brakujące zakresy są wymienione w details.scopes.

Powiązanie​

Powiązanie obejmuje wszystkie pola albo żadne i nie można go zmienić po utworzeniu (token jest pokazywany tylko raz; zmiana powiązania = unieważnienie i nowy klucz). Reguły tworzenia, sprawdzane po stronie serwera i pokazywane od razu w formularzu w panelu:

RegułaSzczegóły
B1Dowolny zakres orders:* ⇒ powiązanie jest wymagane
B2Klucz powiązany ⇒ catalog:write jest zabronione (zapisy PIM pozostają wyłącznie dla kluczy niepowiązanych)
B3Techniczne konto klienta musi być aktywne i należeć do powiązanej organizacji
B4Organizacja i kanał sprzedaży muszą istnieć (kanał nie musi być aktywny przy tworzeniu — klucz po prostu odmawia działania, dopóki kanał jest nieaktywny)
B5expiresAt, jeśli podane, musi wskazywać chwilę w przyszłości

Naruszenie którejkolwiek reguły daje odpowiedź 422 VALIDATION_FAILED, a details wymienia każdy problem jako { path, issue }. Reguła B3 ma trzy przypadki: konto, które nie istnieje, i konto innej organizacji to błędy walidacji, każdy z własnym opisem. Konto powiązanej organizacji, które jest zablokowane, usunięte albo zanonimizowane, odrzuca jego własny stan i gdy jest to jedyny problem, odpowiedzią jest 422 API_KEY_SERVICE_ACCOUNT_INACTIVE z details.field: "binding.customerAccountId", customerAccountId, organizationId i tokenem odmowy w details.code: blocked (odblokuj konto albo wybierz inne) albo removed (konto usunięte lub zanonimizowane; wybierz inne). Operator czyta komunikat we własnym języku. Obok innego problemu nieaktywne konto pozostaje jedną z pozycji listy VALIDATION_FAILED. Do zgłoszenia #644 wszystkie trzy przypadki B3 miały jeden wspólny angielski opis.

W trakcie żądania klucz powiązany ustawia kontekst tenanta ograniczony do jednej organizacji i przypięty kanał sprzedaży (jawny nagłówek X-Sales-Channel wskazujący inny kanał jest odrzucany z 403 API_KEY_CHANNEL_MISMATCH). Klucz niepowiązany zachowuje dotychczasowy kontekst systemowy i wyznaczanie kanału z nagłówka, hosta albo kanału domyślnego.

Ważność​

expiresAt jest opcjonalne i dotyczy obu rodzajów kluczy. Po upływie tej chwili authenticate odrzuca klucz z 401 UNAUTHORIZED — tak samo jak klucz unieważniony.

Encje​

ApiKey (name, keyHash, lastFour, scopes, status, lastUsedAt oraz opcjonalne kolumny powiązania i ważności: organizationId, salesChannelId, customerAccountId, expiresAt).

Odmowy​

  • Brak wymaganego zakresu ⇒ 403 API_KEY_OUT_OF_SCOPE i wpis audytu api_key.out_of_scope.
  • Klucz niepowiązany na endpoincie wymagającym powiązania ⇒ 403 API_KEY_NOT_BOUND i wpis audytu api_key.not_bound.
  • Niezgodny kanał ⇒ 403 API_KEY_CHANNEL_MISMATCH i wpis audytu api_key.channel_mismatch.

Punkty rozszerzenia​

  • Nowe zakresy — rozszerz apiKeyScopeSchema w @endora-commerce/contracts i chroń nową trasę w miejscu wywołania; przy egzekwowaniu usługa nie zależy od nazw zakresów.
  • Limit żądań dla klucza — api-key-service.authenticate zwraca identyfikator klucza; dodaj licznik dla każdego klucza w pre-handlerze albo w dalszej warstwie pośredniej.