Autentificare

FreeMaint acceptă două mecanisme de autentificare: JWT-uri (emise de /auth/login, utilizate de aplicațiile noastre web și mobile) și chei API (create în /company-settings/api, utilizate de propriile integrări).

JWT (sesiuni utilizator)

1. POST /auth/login — Corp: {email, password}. Returnează {access_token, refresh_token}.
2. Trimiteți antetul Authorization — La fiecare cerere: Authorization: Bearer <access_token>.
3. Reîmprospătați la expirare — POST /auth/refresh cu refresh_token pentru a obține un nou access_token. Tokenurile de acces sunt valabile 2 ore.

Cheie API (integrari de server)

1. Deschideți /company-settings/api sau /profile/api-keys — Administratorii creează chei din Setări Companie > API, începând cu planul Business. O persoană al cărei rol are permisiunea „Crearea cheilor API personale” își creează propriile chei din Profil > Securitate > Chei API. Un rol cu permisiunea „Gestionarea integrărilor” (de exemplu șablonul Administrator de integrări) poate crea, revoca și șterge cheile companiei fără a fi administrator; doar un administrator predă o cheie altei persoane.
2. Faceți clic pe „Cheie nouă” — Opțional, setați o dată de expirare și un nivel de acces (implicit Doar citire). Cheia brută este afișată O SINGURĂ DATĂ — copiați-o imediat.
3. Folosește-l — Trimiteți Authorization: Bearer fmk_<rawKey> la fiecare cerere. Format: începe cu fmk_ urmat de 32 de caractere hexazecimale.

Note de securitate

• Cheile API sunt stocate ca hash-uri SHA-256 - odată ce închideți dialogul de revelare, valoarea brută este irecuperabilă
• Revocarea unei chei o dezactivează imediat; rândul este păstrat pentru audit
• Fiecare cheie aparține unei singure companii și ajunge doar la datele acelei companii — o înregistrare a altei companii pur și simplu nu este găsită
• Cheile pot avea un expiresAt opțional pentru integrări de scurtă durată
• Niveluri de acces, un plafon peste permisiunile proprietarului: READ (implicit — doar interogări), READ_STOCK (interogări + adjustStock — ideal pentru un chioșc doar de consum), FULL (orice operațiune permisă de rolul proprietarului)
• Fiecare cheie acționează ca proprietarul ei: fiecare apel poartă permisiunile acestuia și vizibilitatea lui asupra datelor, iar ce scrie cheia este semnat cu numele lui. Dacă proprietarul este dezactivat, cheia este refuzată (401, cod API_KEY_OWNER_INACTIVE) până când un administrator o predă altei persoane din Setări Companie > API — valoarea cheii nu se schimbă.

Testarea unei integrări

Nu există un mediu de testare separat: o cheie API se adresează întotdeauna datelor reale ale companiei căreia îi aparține. Două moduri de a testa în siguranță. (1) Folosiți o a doua companie drept companie de test — izolarea dintre companii este chiar mecanismul care separă toți clienții, așa că nimic din ce faceți acolo nu vă poate atinge datele de producție. Cheile API necesită planul Business, deci și acea companie trebuie să fie pe Business: o companie gratuită nu poate crea o cheie. (2) Pentru lucru doar în citire, creați o cheie cu nivelul de acces READ: rulează orice interogare și nicio mutație, deci nu poate schimba nimic. Când sunteți gata să scrieți, o cheie READ_STOCK permite adjustStock și nimic altceva.