Guida Integrazione Mobile / Client — LifeDome Partner API

⚠️ Gli shape JSON in questa guida sono indicativi. Contratto ufficiale = Schema OpenAPI. In caso di discordanza, prevale lo schema OpenAPI.

---

Modello di integrazione

LifeDome è la piattaforma dati (tracking GPS, telemetria sanitaria, geofence, alert, comandi). Il partner è una società public-provider che possiede la propria relazione con l'utente finale e la propria UI/UX.

Il modello è esclusivamente server-to-server:

• L'app client del partner (Flutter, Android nativo, iOS nativo, React Native, web, ...) non chiama direttamente LifeDome.
• L'app client chiama il backend del partner.
• Il backend del partner si autentica su LifeDome con OAuth2 Client Credentials e agisce per conto dell'utente finale.

Perché:

• L'identità dell'utente è gestita dal partner (login, session, MFA, branding).
• Una sola coppia di credenziali (client_id + client_secret) per partner, non una per utente.
• LifeDome vede solo il principal partner, vincolato alla sua Organization.
• Il partner può imporre logiche proprie di authz, logging, audit, throttling.

Accesso portale opzionale (hybrid):

• Il partner può invitare un utente provisionato ad accedere al portale LifeDome (vedi Invito portale (hybrid access)).
• Dopo l'attivazione via email, l'utente ottiene accesso diretto a LifeDome con JWT/cookie normali, parallelamente al flusso server-to-server.

Esplicitamente rifiutato: OAuth2 user-level (Authorization Code + PKCE) con l'app client che chiama direttamente /api/v1/*. I partner che vogliono quello possono federare tramite il proprio IdP e continuare a proxare tramite backend.

---

Architettura

Componenti

Boundary di tenancy

• Ogni partner integration record è 1:1 con una Organization LifeDome. Il partner vede solo i dati della propria org.
• Il tenant della richiesta è risolto dall'OAuth2 partner auth dal token presentato.
• Le query sono filtrate automaticamente per tenant. Una risorsa di un'altra org risponde 404 Not Found (non 403), per prevenire ID enumeration.

Coesistenza con utenti umani

Gli stessi endpoint /api/v1/* servono anche gli utenti umani del portale LifeDome, che si autenticano via JWT/cookie. Il partner non ha visibilità né impatto su questo flusso umano.

---