Autenticazione

FreeMaint accetta due meccanismi di autenticazione: JWT (emessi da /auth/login, utilizzati dalle nostre app web e mobili) e chiavi API (create in /company-settings/api, utilizzate dalle tue integrazioni).

JWT (sessioni utente)

1. POST /auth/login — Corpo: {email, password}. Restituisce {access_token, refresh_token}.
2. Invia l'header Authorization — A ogni richiesta: Authorization: Bearer <access_token>.
3. Aggiorna quando scaduto — POST /auth/refresh con il refresh_token per ottenere un nuovo access_token. I token di accesso durano 2 ore.

Chiave API (integrazioni server)

1. Apri /company-settings/api o /profile/api-keys — Gli amministratori creano le chiavi in Impostazioni Azienda > API, dal piano Business in su. Una persona il cui ruolo ha il permesso «Creare chiavi API personali» crea le proprie in Profilo > Sicurezza > Chiavi API. Un ruolo con il permesso «Gestire le integrazioni» (per esempio il modello Amministratore delle integrazioni) può creare, revocare ed eliminare le chiavi dell'azienda senza essere amministratore; solo un amministratore affida una chiave a un'altra persona.
2. Fai clic su "Nuova chiave" — Facoltativamente, imposta una scadenza e un livello di accesso (Sola lettura per impostazione predefinita). La chiave grezza viene mostrata UNA SOLA VOLTA: copiala immediatamente.
3. Usalo — Invia Authorization: Bearer fmk_<rawKey> a ogni richiesta. Formato: inizia con fmk_ seguito da 32 caratteri esadecimali.

Note di sicurezza

• Le chiavi API vengono archiviate come hash SHA-256: una volta chiusa la finestra di dialogo di rivelazione, il valore non elaborato è irrecuperabile
• La revoca di una chiave la disabilita immediatamente; la riga viene mantenuta per il controllo
• Ogni chiave appartiene a una sola azienda e raggiunge solo i dati di quell'azienda: un record di un'altra azienda semplicemente non viene trovato
• Le chiavi possono avere un expiresAt facoltativo per le integrazioni di breve durata
• Livelli di accesso, un tetto che si aggiunge ai permessi del proprietario: READ (predefinito — solo query), READ_STOCK (query + adjustStock — ideale per un chiosco di solo prelievo), FULL (ogni operazione consentita dal ruolo del proprietario)
• Ogni chiave agisce come il suo proprietario: ogni chiamata porta i suoi permessi e la sua visibilità sui dati, e ciò che scrive è firmato con il suo nome. Se il proprietario viene disattivato, la chiave viene rifiutata (401, codice API_KEY_OWNER_INACTIVE) finché un amministratore non la affida a un'altra persona in Impostazioni Azienda > API — il valore della chiave non cambia.

Testare un'integrazione

Non esiste un ambiente sandbox separato: una chiave API si rivolge sempre ai dati reali dell'azienda a cui appartiene. Due modi per testare senza rischi. (1) Usi una seconda azienda come azienda di prova — l'isolamento fra aziende è lo stesso meccanismo che separa tutti i clienti, quindi nulla di ciò che fa lì può raggiungere i suoi dati di produzione. Le chiavi API richiedono il piano Business, quindi anche quell'azienda deve essere su Business: un'azienda gratuita non può crearne. (2) Per il lavoro in sola lettura, crei una chiave con livello di accesso READ: può eseguire ogni query e nessuna mutazione, quindi non può modificare nulla. Quando sarà pronto a scrivere, una chiave READ_STOCK consente adjustStock e nient'altro.