Autenticazione e Autorizzazione

Autenticazione

Le API GipoNext richiedono sempre il contesto di un utente autenticato. Non è supportato il flusso Client Credentials (machine-to-machine): ogni token deve essere associato a una persona che ha fatto login in modo interattivo.

Flussi supportati

Flusso	Quando usarlo
Authorization Code	Applicazioni web con backend (PHP, .NET, Java, Python, Node.js) e app native (desktop, mobile) che possono aprire un browser
Device Code	Dispositivi senza browser, CLI, strumenti batch o ambienti server senza interfaccia grafica

In entrambi i casi, l'utente fa login su account.gipo.it, autorizza la tua app e il sistema rilascia un access token che usi per chiamare le API.

Per i dettagli tecnici di implementazione (parametri, endpoint, sequence diagram, gestione dei token e del refresh), vedi Flussi OAuth e token.

Autorizzazione (Scope OAuth)

Gli scope definiscono a quali risorse la tua applicazione può accedere tramite le API GipoNext. Funzionano come un sistema di permessi dichiarativi: la tua app dichiara ciò di cui ha bisogno, l'utente decide a quali concedere l'accesso.

Come funzionano

Il ciclo di vita degli scope segue tre passaggi:

1. Registrazione — Quando registri la tua applicazione su account.gipo.it, dichiari la lista di scope a cui vuoi avere accesso. Questa lista rappresenta il perimetro massimo di funzionalità che la tua app potrà utilizzare (vedi Registrare l'applicazione).

2. Consenso dell'utente — Quando un utente fa login tramite la tua applicazione, vede una schermata di consenso con l'elenco dei permessi richiesti. L'utente può accettare o rifiutare ciascuno scope. Se l'utente non concede uno scope, la tua app non potrà usare le funzionalità corrispondenti per quella sessione.

3. Utilizzo nel token — L'access token che ricevi contiene solo gli scope effettivamente concessi dall'utente. Ogni chiamata API è limitata a quegli scope: se provi a usare un endpoint non coperto, riceverai un errore 403 Forbidden.

Gestire il consenso parziale

La tua applicazione deve prevedere il caso in cui l'utente non conceda tutti gli scope richiesti. Dopo aver ottenuto l'access token, confronta gli scope presenti nella risposta con quelli di cui hai bisogno:

• Disabilita le funzionalità non coperte dagli scope concessi, mostrando un messaggio chiaro all'utente.
• Non bloccare l'intera applicazione se manca uno scope non essenziale per la funzione corrente.
• Se necessario, guida l'utente a concedere i permessi mancanti avviando un nuovo flusso di autorizzazione con gli scope aggiuntivi.

💡 Best practice: scope incrementali

Richiedi gli scope nel momento in cui servono, non tutti in anticipo.

Ad esempio, richiedi giponext.invoices solo quando l'utente accede alla sezione fatturazione della tua app.

Gli utenti tendono ad accettare più volentieri permessi richiesti nel contesto giusto.

Scope disponibili

La tabella elenca tutti gli scope che puoi richiedere durante la registrazione della tua applicazione.

Scope	Funzionalità
openid	Flusso OpenID Connect base (obbligatorio per tutti i client)
offline_access	Rilascio del refresh token per rinnovare l'accesso senza nuovo login
giponext.patients	Pazienti — lettura e scrittura anagrafiche
giponext.agenda	Agende, disponibilità e appuntamenti — lettura e gestione calendario
giponext.treatments	Prestazioni e listini — lettura catalogo e prezzi
giponext.episodes	Episodi clinici — lettura e scrittura percorsi paziente
giponext.medicalreports	Referti — lettura e scrittura documentazione clinica
giponext.invoices	Fatturazione — lettura e scrittura documenti di vendita

Per la mappa completa tra scope e risorse API disponibili, vedi Entità e operazioni.

Modificare gli scope dopo la registrazione

La modifica degli scope associati a un'applicazione non è disponibile in self-service. Se hai bisogno di aggiungere o rimuovere scope dalla tua app, contatta il supporto integrazioni scrivendo al supporto specificando:

• il client_id della tua applicazione;
• gli scope da aggiungere o rimuovere;
• la motivazione della variazione.

Prossimi passi

• Flussi OAuth e token — implementazione tecnica dei flussi OAuth
• Registrare l'applicazione — come ottenere client_id e configurare gli scope
• Entità e operazioni — mappa risorse, operazioni e scope richiesti per endpoint
• Credenziali sviluppatore e credenziali di accesso al sistema — perché servono due identità