Autenticazione OAuth2

Protocollo: OAuth2 Client Credentials (RFC 6749 §4.4). Il flusso server-to-server gira esclusivamente sul backend partner, mai sul client mobile/web. Qualsiasi libreria OAuth2 conforme è supportata — non è richiesta alcuna integrazione specifica con LifeDome al di là dello standard.

Endpoint token

Proprietà	Valore
Metodo / path	POST /o/token/
Content-Type richiesta	application/x-www-form-urlencoded
Autenticazione client	HTTP Basic (client_id + client_secret) oppure coppia nel body
Grant	client_credentials
Scope (opzionale)	Lista separata da spazi; validati contro il catalogo globale di scope. Omesso ⇒ il token viene emesso senza scope (default []) e tutte le chiamate scope-gated rispondono 403 insufficient_scope

Campi del body richiesta:

Campo	Obbligatorio	Note
grant_type	Sì	Valore fisso: client_credentials
scope	No	Lista separata da spazi. Se omesso il token è privo di scope — dichiara sempre esplicitamente quelli che servono
client_id / client_secret	Solo se non si usa Basic auth	In alternativa all'header Authorization

Nota sull'allow-list di scope: l'allow-list assegnata al partner in fase di onboarding è validata al token endpoint. Scope richiesti fuori dall'allow-list per-integrazione → 400 invalid_scope. Doppia validazione: catalogo globale di scope + sottoinsieme dell'allow-list del partner.

Response 200 — struttura:

{
  "access_token": "<stringa opaca>",
  "token_type": "Bearer",
  "expires_in": 300,
  "scope": "<scope concessi>"
}

Proprietà del token

Proprietà	Valore
Durata	5 minuti (300 s)
Tipo	Opaco (non JWT)
Revoca	Immediata via endpoint standard /o/revoke_token/ (RFC 7009)
Refresh token	Non emesso (RFC 6749 §4.4.3)
Transport	Solo HTTPS

Il backend partner deve cachare il token in memoria e ri-autenticarsi alla scadenza (overhead di emissione trascurabile).

Uso su ogni richiesta

Ogni chiamata a /api/v1/* deve includere l'header Authorization con schema Bearer e il token opaco come valore.

Errori /o/token/ (RFC 6749 §5.2)

HTTP	error	Causa
400	invalid_request	Parametri mancanti/malformati
400	invalid_grant	Grant non supportato da questa application
400	invalid_scope	Scope richiesto non presente nel catalogo globale
401	invalid_client	Credenziali client_id / client_secret errate. Lo stato SUSPENDED / REVOKED del partner non è enforced qui: il token viene emesso comunque, ma ogni chiamata a /api/v1/* restituisce 401.

Rotazione credenziali

LifeDome può emettere una seconda coppia client_id / client_secret affiancata alla prima. Flusso consigliato:

1. LifeDome emette nuova credenziale e la comunica al partner.
2. Partner deploya la nuova credenziale side-by-side.
3. Partner verifica traffico con nuova credenziale.
4. Partner chiede la revoca della vecchia.

Zero downtime.

---

Scope

Le scope seguono la convenzione resource:permission. Sono concesse per partner in fase di onboarding; i token emessi possono tenerne un sottoinsieme (passando scope=... al token endpoint).

Scope	Concede
users:read	Lista / dettaglio utenti nella org del partner
users:write	Crea / aggiorna / deattiva utenti
users:invite	Invia email attivazione portale
devices:read	Lista / dettaglio dispositivi
devices:write	Registra (POST), aggiorna (PATCH) e cancella (DELETE) dispositivi
assignments:read	Lista / dettaglio assegnazioni dispositivo (tutti i ruoli)
assignments:write	Assegna / disassegna come OWNER o ASSIGNED
assignments:share	Condividi dispositivo come VIEWER (flusso invito) / revoca share
locations:read	Posizioni (latest + storico + segmenti)
telemetry:read	Telemetria sanitaria scalare (latest + storico)
ecg:read	Registrazioni ECG (waveform incluso). Scope dedicato — telemetry:read non lo copre.
events:read	Eventi / allarmi
events:acknowledge	Acknowledge eventi
commands:read	Stato comandi
commands:write	Invia / cancella comandi
messaging:read	Leggi messaggi device (opt-in per partner)
messaging:write	Invia / elimina messaggi device
geofences:read	Leggi geofence
geofences:write	Crea / aggiorna / elimina geofence, assegna device
thresholds:read	Leggi soglie di allerta
thresholds:write	Crea / aggiorna / elimina soglie
catalog:read	Catalogo protocolli / modelli / capability
invitations:read	Leggi inviti pending
invitations:write	Accetta / revoca inviti
audit:read	Leggi audit log proprio della org
org:read	Metadata della propria org (feature, limiti)

Regole globali:

1. Scope dichiarati esplicitamente. Token emesso senza il parametro scope = token senza scope. Chiamata a endpoint scope-gated senza lo scope richiesto → 403 insufficient_scope. Scope fuori catalogo globale → 400 invalid_scope al token endpoint.
2. Default-deny. Lo schema OpenAPI elenca solo gli endpoint raggiungibili via partner auth: qualunque altro endpoint risponde 403 scope_not_available.
3. Allow-list per integrazione enforced runtime. L'allow-list di scope assegnata al partner è validata al token endpoint. Scope fuori dall'allow-list → 400 invalid_scope. Chiedi solo ciò che ti è stato concesso in fase di onboarding.

---