Tenant

Un tenant rappresenta un centro medico all'interno di GipoNext. Ogni clinica, studio o poliambulatorio che utilizza GipoNext è un tenant separato, identificato da un tenantId univoco.

Il tenantId è il discriminante fondamentale di tutte le chiamate API: distingue i dati di un centro medico da quelli di un altro. Pazienti, appuntamenti, fatture, referti e ogni altra risorsa appartengono sempre a un tenant specifico e non sono visibili né accessibili dagli altri.

Nella pratica, quasi tutti gli endpoint delle API hanno la forma:

/v2/tenants/{tenantId}/...

Il tenantId compare nel path perché ogni operazione avviene nel contesto di un singolo centro medico.

Come ottenere il tenantId

Ogni utente GipoNext appartiene a un solo tenant, stabilito al momento della creazione dell'account. Non è possibile cambiare tenant in corso di sessione né accedere a tenant diversi dal proprio.

Dopo il login OAuth, il primo passo è chiamare l'endpoint UserInfo per scoprire a quale tenant è collegato l'utente autenticato:

GET https://api.giponext.it/v2/userinfo
Authorization: Bearer <access_token>

{
  "sub": "user-id",
  "name": "Mario Rossi",
  "tenants": [
    { "id": "tenant-abc123", "name": "Clinica Esempio" }
  ]
}

Il campo tenants contiene il tenant dell'utente. Usa il valore id come {tenantId} in tutte le chiamate successive.

Nessun filtro per tenant sull'applicazione

La tua applicazione OAuth non filtra a priori gli utenti in base al tenant di appartenenza. Questo significa che virtualmente qualsiasi utente GipoNext attivo può autenticarsi tramite la tua app, indipendentemente dalla clinica a cui appartiene.

In pratica: se la tua integrazione è pensata per un singolo centro medico, nulla impedisce a un utente di un altro centro di fare login. Il sistema OAuth verifica solo che l'utente sia valido e che la tua app sia approvata, ma non controlla a quale clinica appartiene.

Filtrare il tenant è responsabilità dell'integratore

Se la tua logica applicativa prevede di operare solo con uno o più tenant specifici, devi implementare tu il controllo dopo il login:

1. Chiama /v2/userinfo per ottenere il tenantId dell'utente.
2. Confronta il tenantId con la lista dei tenant autorizzati dalla tua applicazione.
3. Se il tenant non è tra quelli previsti, rifiuta l'accesso e mostra un messaggio chiaro all'utente (es. "Questa applicazione è riservata alla Clinica XYZ").

⚠️ Attenzione

Non affidarti al fatto che "solo gli utenti giusti conoscono le credenziali". La sicurezza per tenant deve essere implementata esplicitamente nel tuo codice.

Ambiente sandbox

Per lo sviluppo e il test della tua integrazione non è necessario accedere al tenant del cliente finale. Anzi, è buona pratica non farlo mai durante la fase di sviluppo: il tenant di produzione contiene dati sanitari reali soggetti a normative sulla privacy.

Gipo mette a disposizione di ogni integratore un tenant sandbox: un ambiente isolato, vuoto in partenza, dove puoi:

• creare pazienti, appuntamenti, fatture e referti fittizi;
• testare tutti i flussi (creazione, lettura, aggiornamento, cancellazione) senza rischi;
• validare il comportamento della tua app end-to-end prima del passaggio in produzione;
• mostrare al cliente un prototipo funzionante senza coinvolgere dati reali.

Il tenant sandbox è completamente separato dai tenant di produzione: nulla di ciò che fai in sandbox ha effetto sui dati dei centri medici.

💡 Chiedi il tuo tenant sandbox

Se non ne hai ancora uno, richiedi l'attivazione scrivendo al supporto. Lo riceverai pronto all'uso con le credenziali di accesso.

Quando accedere al tenant di produzione

L'accesso ai dati reali del centro medico avviene solo a sviluppo completato, su richiesta esplicita del centro medico stesso. La procedura è descritta in Registrare l'applicazione — Accesso ai dati di produzione.

Prossimi passi

• Entità e operazioni — risorse disponibili per tenant e scope richiesti
• Autenticazione e autorizzazione — come funziona il login OAuth
• Credenziali sviluppatore e credenziali di accesso al sistema — perché servono due identità
• Registrare l'applicazione — provisioning OAuth e accesso ai dati di produzione