Klucze API - nadawanie uprawnień na interfejsy REST

Mechanizm kluczy API z zakresami dostępu i ścieżkami akceptacji pozwala na tworzenie kluczy o minimalnym zbiorze uprawnień. Przykład ten opisuje, w jaki sposób zdefiniować klucz dostępu do wybranych interfejsów REST systemu AMAGE - zarówno dla integracji z zewnętrznym systemem (na przykład ERP), jak i dla urządzenia mobilnego pracującego offline.

Cel

W wdrożeniu chcemy udostępnić zewnętrznej aplikacji dostawcy dostęp do wybranych interfejsów REST systemu AMAGE, ale nie do całego API. Dzięki zakresom dostępu i ścieżkom akceptacji:

  • klucz daje dostęp tylko do wybranych ścieżek (na przykład do interfejsów zleceń pracy i zasobów)

  • zakres dostępu ogranicza klucz do publicznego REST - nie ma on dostępu do interfejsów mobilnych ani AI

  • w razie wycieku klucza narażenie ryzyka jest ograniczone do zdefiniowanego zbioru interfejsów

Krok 1: Zdefiniowanie klucza API

Przechodzimy do sekcji Konfiguracja > Klucze dostępu (interfejs zarządzania kluczami dostępu). Wybieramy akcję dodania nowego klucza.

Dane klucza:

  • Nazwa - opisowa nazwa klucza, na przykład "Dostawca XYZ - interfejs ERP"

  • Zakresy dostępu (funkcje) - zaznaczamy tylko Publiczne REST (nie zaznaczamy Mobile, Embedded ani AI)

  • Ścieżki akceptacji - wprowadzamy listę patternów ścieżek REST, do których klucz ma mieć dostęp, na przykład:

    • /amage/workorders/* - odczyt i operacje na zleceniach pracy

    • /amage/assets/* - odczyt danych zasobów

    • /amage/customers/by-nip - wyszukanie klienta po NIP

Po zapisaniu klucza system generuje unikalny UUID oraz sekret API. Dane te przekazujemy integratorowi zgodnie z procedurą bezpiecznego przekazywania sekretów.

Krok 2: Weryfikacja dostępu

Po otrzymaniu klucza integrator może wykonać testowe wywołania:

  • wywołanie ścieżki /amage/workorders/list - zwrócone dane (dostęp zgodny z zakresami)

  • wywołanie ścieżki /ai/v1/mcp - odrzucone (klucz nie ma zakresu AI)

  • wywołanie ścieżki /sync/state - odrzucone (klucz nie ma zakresu Mobile)

  • wywołanie ścieżki /amage/inventory/* - odrzucone (ścieżka poza zdefiniowanymi ścieżkami akceptacji)

Krok 3: Wymiana klucza

Klucze można wygenerować ponownie lub usunąć. W przypadku podejrzenia wycieku klucza należy:

  • wygenerować nowy sekret dla istniejącego klucza lub usunąć stary i utworzyć nowy

  • poinformować integratora o zmianie i przekazać mu nowe dane

Uwagi

  • Klucze API starszej generacji (utworzone przed rozszerzeniem o zakresy) zachowują pełny dostęp do interfejsów REST i nie mogą być modyfikowane w zakresie uprawnień. W celu ich ograniczenia należy utworzyć nowy klucz z zakresami i zastąpić stary.

  • Daty ważności klucza powinny być stosowane w połączeniu z okresowym rotowaniem sekretów.

  • Szczegółowy opis interfejsu zarządzania kluczami znajduje się w sekcji dokumentacji konfiguracyjnej: Interfejs zarządzania kluczami dostępu.