Documentazione

Autenticazione

Effettua il login come utente dell'organizzazione per ottenere un token di sessione, poi invialo come Bearer su ogni chiamata. Il token resta valido 7 giorni.

Ottieni un token con il login presso l'Auth server, poi usalo come Bearer verso l'API.

Dove usare il token

Il login avviene sull'Auth server (https://auth.spectraholo.it); tutte le altre chiamate vanno all'API server (https://api.spectraholo.it) con l'header Authorization: Bearer <token>.

Autenticazione

Login e logout dell'utente sul server di autenticazione. Il token di sessione restituito dal login va poi usato come Bearer token su tutte le chiamate protette dell'API.

POSThttps://auth.spectraholo.it/v1/organization/{organizationId}/user/loginPubblico

Login utente

Autentica un utente verificando email e password rispetto a un'organizzazione. In caso di successo crea una sessione e restituisce un token opaco (sia nel corpo JSON sia in un cookie httpOnly) insieme a un sessionId numerico per la gestione della sessione. È prevista una protezione anti-bruteforce: i tentativi falliti ripetuti sulla stessa coppia organizzazione+email attivano un throttling con backoff esponenziale. Gli errori di utente inesistente e di password errata restituiscono entrambi un 401 generico per non rivelare se un'email esista.

Autenticazione: Pubblico — nessuna autenticazione

Parametri del percorso

organizationId* Identificatore intero dell'organizzazione (>= 0). Può essere passato come numero o come stringa numerica.

Corpo della richiesta · application/json

`email`* string	Indirizzo email valido dell'utente. Normalizzato in minuscolo; deve corrispondere al pattern ^[^\s@]+@[^\s@]+\.[^\s@]+$
`password`* string	Password dell'utente in chiaro. Deve essere non vuota e non superare i 128 caratteri (controllo per evitare un DoS sulla CPU dovuto a input scrypt arbitrariamente lunghi).

Esempio di corpo (JSON)

{
  "email": "mario.rossi@azienda.it",
  "password": "Password-2026!"
}

Risposta200

{
  "success": true,
  "message": "Login successful",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "sessionId": 42,
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "organizationId": 1
  }
}

Errori

400Corpo JSON non valido, organizationId mancante/non valido, email mancante/non valida oppure password mancante/non valida
401Utente con l'email indicata non trovato nell'organizzazione oppure la password non corrisponde all'hash memorizzato
429Troppi tentativi di login falliti sulla stessa coppia organizzazione+email; il client deve riprovare dopo un'attesa
500Errore interno del server (es. guasto del database)

POSThttps://auth.spectraholo.it/v1/organization/{organizationId}/user/logoutAuthority ≥ 0 · Lettura

Logout utente

Effettua il logout (elimina) di una sessione utente. Supporta tre modalità in base alle credenziali fornite: (1) token di sessione utente via cookie senza sessionId, che chiude la sessione corrente e azzera il cookie; (2) backend API key + sessionId nel corpo, per chiudere qualsiasi sessione dell'organizzazione; (3) token di sessione utente + sessionId nel corpo, che chiude una sessione specifica solo se appartiene allo stesso utente. Il token di sessione viaggia nel cookie 'spectra_session'; l'ID numerico della sessione (se fornito) viaggia nel corpo della richiesta.

Autenticazione: Token utente (Bearer) — qualsiasi membro

Parametri del percorso

organizationId* ID dell'organizzazione (intero non negativo). Passato come parametro di percorso nell'URL.

Corpo della richiesta · application/json

sessionIdfacolt.

number

ID numerico della sessione da chiudere. Se omesso con autenticazione utente, chiude la sessione corrente (dal token nel cookie). Se fornito, deve essere un intero positivo (>= 1).

Esempio di corpo (JSON)

{
  "sessionId": 42
}

Risposta200

{
  "success": true,
  "message": "Logged out successfully",
  "sessionId": 42
}

Errori

400organizationId non è un intero non negativo, oppure sessionId (se fornito) non è un intero positivo
400L'header backend API key è presente ma sessionId manca nel corpo
401L'header backend API key è presente ma la chiave non è valida
401Nessun cookie di sessione trovato e nessuna backend API key valida fornita
401Token di sessione non valido, scaduto oppure non appartenente all'organizzazione indicata
404La sessione con il sessionId indicato non esiste nell'organizzazione (modalità backend) oppure non appartiene all'utente corrente (modalità utente)
500Errore interno del server (guasto del database, ecc.)

PrecedenteEndpoint di produzione SuccessivoOrganizzazione