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żka | Kto | Przeznaczenie |
|---|---|---|
GET /api/v1/admin/api-keys | administrator | Lista kluczy z datą ostatniego użycia, powiązaniem i datą ważności |
POST /api/v1/admin/api-keys | administrator | Utworzenie; zwraca token bearer tylko raz |
DELETE /api/v1/admin/api-keys/:id | administrator | Unieważ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):
| Zakres | Znaczenie |
|---|---|
catalog:read | Odczyty PIM (klucz niepowiązany) i zewnętrzne API katalogu (klucz powiązany) |
catalog:write | Zapis PIM według SKU — tylko klucze niepowiązane |
orders:read | Odczyt zamówień przez zewnętrzne API — tylko klucze powiązane |
orders:write | Przyjmowanie zamówień przez zewnętrzne API — tylko klucze powiązane |
platform.api_description.read | Opis 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ła | Szczegóły |
|---|---|
| B1 | Dowolny zakres orders:* ⇒ powiązanie jest wymagane |
| B2 | Klucz powiązany ⇒ catalog:write jest zabronione (zapisy PIM pozostają wyłącznie dla kluczy niepowiązanych) |
| B3 | Techniczne konto klienta musi być aktywne i należeć do powiązanej organizacji |
| B4 | Organizacja i kanał sprzedaży muszą istnieć (kanał nie musi być aktywny przy tworzeniu — klucz po prostu odmawia działania, dopóki kanał jest nieaktywny) |
| B5 | expiresAt, 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_SCOPEi wpis audytuapi_key.out_of_scope. - Klucz niepowiązany na endpoincie wymagającym powiązania ⇒
403 API_KEY_NOT_BOUNDi wpis audytuapi_key.not_bound. - Niezgodny kanał ⇒
403 API_KEY_CHANNEL_MISMATCHi wpis audytuapi_key.channel_mismatch.
Punkty rozszerzenia
- Nowe zakresy — rozszerz
apiKeyScopeSchemaw@endora-commerce/contractsi 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.authenticatezwraca identyfikator klucza; dodaj licznik dla każdego klucza w pre-handlerze albo w dalszej warstwie pośredniej.