Uwierzytelnianie

FreeMaint akceptuje dwa mechanizmy uwierzytelniania: JWT (wydawane przez /auth/login, używane przez nasze aplikacje internetowe i mobilne) oraz klucze API (tworzone w /company-settings/api, używane przez Twoje własne integracje).

JWT (sesje użytkowników)

1. POST /auth/login — Treść: {email, password}. Zwraca {access_token, refresh_token}.
2. Wyślij nagłówek Authorization — Przy każdym żądaniu: Authorization: Bearer <access_token>.
3. Odśwież po wygaśnięciu — POST /auth/refresh z refresh_token, aby uzyskać nowy access_token. Tokeny dostępu są ważne 2 godziny.

Klucz API (integracje serwerów)

1. Otwórz /company-settings/api lub /profile/api-keys — Administratorzy tworzą klucze w Ustawienia firmy > API, od planu Business wzwyż. Osoba, której rola ma uprawnienie „Tworzenie osobistych kluczy API”, tworzy własne w Profil > Bezpieczeństwo > Klucze API. Rola z uprawnieniem „Zarządzanie integracjami” (na przykład szablon Administrator integracji) może tworzyć, unieważniać i usuwać klucze firmy bez uprawnień administratora; przekazać klucz innej osobie może tylko administrator.
2. Kliknij „Nowy klucz” — Opcjonalnie ustaw datę wygaśnięcia i poziom dostępu (domyślnie Tylko do odczytu). Surowy klucz zostanie wyświetlony tylko RAZ — skopiuj go natychmiast.
3. Użyj tego — Przy każdym żądaniu wysyłaj nagłówek Authorization: Bearer fmk_<rawKey>. Format: zaczyna się od fmk_, po którym następują 32 znaki szesnastkowe.

Uwagi dotyczące bezpieczeństwa

• Klucze API są przechowywane jako skróty SHA-256 — po zamknięciu okna dialogowego surowej wartości nie można odzyskać
• Unieważnienie klucza powoduje natychmiastową jego dezaktywację; wiersz jest zachowywany do celów audytu
• Każdy klucz należy do jednej firmy i sięga wyłącznie do jej danych — rekord innej firmy po prostu nie zostanie znaleziony
• Klucze mogą mieć opcjonalne pole expiresAt na potrzeby krótkotrwałych integracji
• Poziomy dostępu, czyli pułap nałożony na uprawnienia właściciela: READ (domyślny — tylko zapytania), READ_STOCK (zapytania + adjustStock — idealny dla kiosku tylko do pobrań), FULL (każda operacja, na którą pozwala rola właściciela)
• Każdy klucz działa jako jego właściciel: każde wywołanie niesie jego uprawnienia i jego widoczność danych, a to, co klucz zapisuje, jest podpisane jego nazwiskiem. Jeśli właściciel zostanie dezaktywowany, klucz jest odrzucany (401, kod API_KEY_OWNER_INACTIVE), dopóki administrator nie przekaże go innej osobie w Ustawienia firmy > API — wartość klucza się nie zmienia.

Testowanie integracji

Nie ma osobnego środowiska testowego: klucz API zawsze sięga do prawdziwych danych firmy, do której należy. Są dwa bezpieczne sposoby testowania. (1) Używaj drugiej firmy jako firmy testowej — izolacja między firmami to ten sam mechanizm, który oddziela wszystkich klientów, więc nic, co tam zrobisz, nie sięgnie danych produkcyjnych. Klucze API wymagają planu Business, więc ta firma również musi być na planie Business: bezpłatna firma nie może utworzyć klucza. (2) Do pracy tylko do odczytu utwórz klucz o poziomie dostępu READ: wykona każde zapytanie i żadnej mutacji, więc nie zmieni absolutnie niczego. Gdy przyjdzie pora na zapis, klucz READ_STOCK zezwala na adjustStock i nic więcej.