Membri & utenti

Elenco dei membri

Recupera l'elenco completo di tutti i membri (utenti) dell'organizzazione indicata. Per ogni membro restituisce i dati di profilo pubblici: id, nome, cognome, username, email, URL dell'avatar (null se non impostato), data di nascita e indirizzo. L'autenticazione accetta un token di sessione valido (Bearer o cookie) per qualsiasi utente dell'organizzazione con livello AUTHORITY_VIEW o superiore, oppure una backend API key per le chiamate server-to-server.

Parametri del percorso

Esempio di richiesta

GET https://api.spectraholo.it/v1/organization/42/members

Risposta200

{
  "members": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "firstName": "John",
      "lastName": "Doe",
      "username": "johndoe",
      "email": "john@example.com",
      "avatarUrl": "https://api.spectraholo.it/avatars/org/123/user/550e8400-e29b-41d4-a716-446655440000/avatar.png",
      "birthDate": "1990-05-15",
      "address": "123 Main St"
    }
  ]
}

Errori

• 400ID dell'organizzazione non valido (non numerico o fuori intervallo)
• 401Nessuna autenticazione valida fornita (token di sessione e backend API key mancanti, oppure entrambi non validi)
• 502Il server di autenticazione è irraggiungibile o restituisce un errore durante la validazione della sessione

Crea un utente

Crea un nuovo utente nell'organizzazione indicata, replicando i dati nel database locale (senza password) e sul server di autenticazione (con password hashata e livello di authority). Se non viene fornito un avatar, ne viene generato uno automaticamente. Sono supportate due modalità di autenticazione: backend API key (header x-backend-api-key) oppure sessione utente con authority >= 3 (amministratore).

Parametri del percorso

Corpo della richiesta · multipart/form-data

Esempio di richiesta

POST https://api.spectraholo.it/v1/organization/42/user

# Campi del modulo (multipart/form-data)
email          = mario.rossi@azienda.it
firstName      = Mario
lastName       = Rossi
username       = mario.rossi
password       = Password-2026!
authorityLevel = 2
birthDate      = 1990-05-15
address        = Via Roma 1, Milano
avatar         = @avatar.png

Risposta201

{
  "success": true,
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "organizationId": 42,
    "username": "john.doe",
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com",
    "authorityLevel": 2,
    "createdAt": "2026-06-15T10:30:00.000Z",
    "avatarUrl": "https://api.spectraholo.it/avatars/42/550e8400-e29b-41d4-a716-446655440000?v=abc123"
  }
}

Errori

• 400Il corpo non è multipart/form-data, campi obbligatori mancanti o non validi (email, username, password, data, authority level), immagine avatar in formato non supportato
• 401Backend API key assente o non valida, oppure sessione non valida / scaduta
• 403Sessione valida ma utente con authority < 3 (insufficiente per l'amministrazione degli utenti)
• 404L'organizzazione non esiste
• 409Username o email già in uso nell'organizzazione, oppure l'organizzazione ha raggiunto il limite massimo di utenti
• 413L'avatar supera il limite di dimensione (max 2 MB)
• 502Il server di autenticazione è irraggiungibile o fallisce durante la registrazione dell'utente

Aggiorna email/authority di un utente

Aggiorna l'indirizzo email e/o il livello di authority di un utente all'interno dell'organizzazione. Il livello di authority dell'utente principale non può essere abbassato sotto 3 (errore 409). È un'azione amministrativa che richiede livello AUTHORITY_ADMIN (3) o una backend API key. L'aggiornamento viene validato localmente e propagato al server di autenticazione (fonte di verità per credenziali e authority).

Parametri del percorso

Corpo della richiesta · application/json

Esempio di corpo (JSON)

{
  "email": "mario.rossi@azienda.it",
  "authorityLevel": 2
}

Risposta200

{
  "success": true,
  "message": "User successfully updated!",
  "userId": "550e8400-e29b-41d4-a716-446655440000"
}

Errori

• 400Il corpo della richiesta non è JSON valido, oppure i tipi dei campi richiesti sono errati
• 400Né il campo 'email' né 'authorityLevel' sono forniti (niente da aggiornare)
• 400Formato email non valido (manca il simbolo @ o il dominio)
• 400authorityLevel non è un intero o è fuori dall'intervallo 0–3
• 401Nessuna autenticazione valida fornita (header backend API key mancante e/o token di sessione non valido)
• 403Il livello di authority dell'utente della sessione è inferiore a 3 (richiesto AUTHORITY_ADMIN)
• 404Organizzazione o utente non trovati
• 409L'email è già in uso all'interno dell'organizzazione
• 409Tentativo di abbassare l'utente principale dell'organizzazione sotto il livello di authority 3
• 502Il server di autenticazione è irraggiungibile o fallisce nell'aggiornare credenziali/authority dell'utente

Rimuovi un utente

Rimuove un utente dall'organizzazione, eliminando il record locale e propagando la rimozione al server di autenticazione (che a cascata invalida tutte le sessioni attive di quell'utente). L'utente principale dell'organizzazione non può essere eliminato (solo tramite l'eliminazione dell'organizzazione). È un'azione amministrativa che richiede livello AUTHORITY_ADMIN (3) o una backend API key.

Parametri del percorso

Esempio di richiesta

DELETE https://api.spectraholo.it/v1/organization/42/user/550e8400-e29b-41d4-a716-446655440000

Risposta200

{
  "success": true,
  "message": "User successfully deleted!",
  "userId": "550e8400-e29b-41d4-a716-446655440000"
}

Errori

• 401Nessuna autenticazione valida fornita (header backend API key mancante e/o token di sessione non valido)
• 403Il livello di authority dell'utente della sessione è inferiore a 3 (richiesto AUTHORITY_ADMIN)
• 404Organizzazione non trovata
• 404Utente non trovato nell'organizzazione
• 409Tentativo di eliminare l'utente principale dell'organizzazione (non eliminabile; occorre eliminare l'intera organizzazione)
• 502Il server di autenticazione è irraggiungibile o fallisce nel rimuovere l'utente

Aggiorna il profilo di un membro

Aggiorna le informazioni di profilo di un membro (nome, cognome, username, data di nascita, residenza). L'email non può essere modificata tramite questo endpoint. Richiede authority di org-admin oppure una backend API key (console del superadmin).

Parametri del percorso

Corpo della richiesta · application/json

Esempio di corpo (JSON)

{
  "firstName": "Mario",
  "lastName": "Rossi",
  "username": "mario.rossi",
  "birthDate": "1990-05-15",
  "address": "Via Roma 1, Milano"
}

Risposta200

{
  "success": true,
  "message": "Member profile updated.",
  "userId": "550e8400-e29b-41d4-a716-446655440000"
}

Errori

• 400Campi obbligatori mancanti (firstName, lastName, username), formato non valido (regex username, data YYYY-MM-DD) oppure corpo JSON non valido
• 401Bearer token (sessione) mancante o non valido e nessuna backend API key presente
• 403Il token di sessione è valido ma il livello di authority dell'utente è inferiore a 3 (AUTHORITY_ADMIN)
• 404Utente non trovato nell'organizzazione indicata
• 409Username già in uso all'interno dell'organizzazione
• 502Il server di autenticazione è irraggiungibile o la richiesta fallisce durante la validazione della sessione

Avatar di un utente

Recupera l'immagine dell'avatar di un utente specifico all'interno di un'organizzazione. L'avatar viene servito dallo storage cloud con header di sicurezza che impediscono l'esecuzione di contenuto attivo (SVG, HTML) qualora servito come immagine. Le risposte includono header di cache control.

Parametri del percorso

Esempio di richiesta

GET https://api.spectraholo.it/v1/organization/42/user/550e8400-e29b-41d4-a716-446655440000/avatar

Risposta200

Binary image data (PNG/JPEG/GIF/WEBP format)

Errori

• 404Avatar non trovato per l'utente indicato

Aggiorna l'avatar di un utente

Aggiorna l'immagine dell'avatar di un utente specifico all'interno di un'organizzazione. Richiede una richiesta multipart/form-data con il file immagine nel campo 'avatar'. Solo gli amministratori dell'organizzazione (authority 3) o la backend API possono eseguire questa azione. I formati immagine supportati sono PNG, JPEG, GIF e WEBP. La dimensione massima del file è MAX_AVATAR_BYTES (tipicamente 2 MB). Il formato dell'immagine viene verificato ispezionando i magic bytes, non il content-type dichiarato.

Parametri del percorso

Corpo della richiesta · multipart/form-data

Esempio di richiesta

POST https://api.spectraholo.it/v1/organization/42/user/550e8400-e29b-41d4-a716-446655440000/avatar

# Campi del modulo (multipart/form-data)
avatar = @avatar.png

Risposta200

{
  "message": "Avatar updated.",
  "avatarUrl": "https://api.spectraholo.it/avatars/org-123/user-456.png"
}

Errori

• 400Il corpo della richiesta non è multipart/form-data valido, oppure il campo avatar è mancante o vuoto
• 400Il formato dell'immagine dell'avatar non è supportato (sono ammessi solo PNG, JPEG, GIF, WEBP)
• 401Nessuna autenticazione valida fornita (token di sessione e backend API key mancanti)
• 403Il token di sessione è valido ma il livello di authority dell'utente è inferiore ad ADMIN (livello 3)
• 404L'utente non esiste nell'organizzazione indicata
• 413La dimensione del file dell'avatar supera il limite massimo (circa 2 MB)
• 502Il server di autenticazione è irraggiungibile o fallisce nel validare la sessione