Strumenti

Accesso alle API di CART

Le API gestite da CART sono accessibili, esclusivamente tramite protocollo HTTPS, a tre diversi indirizzi:

  • api.regione.toscana.it: riservato agli accessi da Internet alle API erogate da Regione Toscana. Su questo endpoint è inoltre presente il contesto ‘/sanita’ per le API relative al dominio della sanità regionale;
  • api.rt.tix.it: è un punto di accesso alternativo alle medesime API esposte da api.regione.toscana.it, raggiungibile esclusivamente dagli applicativi installati sulla rete privata regionale del TIX;
  • api.rete.toscana.it: è il punto di accesso dedicato alle API di amministrazioni del territorio regionale diverse da Regione Toscana; le API di ogni amministrazione sono indirizzate da un contesto con identificatore dell’amministrazione erogatrice. Ad esempio: https://api.rete.toscana.it/CPisa/sample-api/v1/…

Per ognuno di questi punti di accesso sono definiti diversi “canali” che possono differenziarsi per il livello di servizio offerto, perché dedicati a specifici domini applicativi o per la diversa versione dell’implementazione della medesima infrastruttura CART. I canali sono individuati da semplici identificatori del tipo CXX utilizzati come parte dell’endpoint di accesso al servizio. Ad esempio:

  • https://api.regione.toscana.it/C01/sample-api/v1/…
  • https://api.regione.toscana.it/C02/sample-api/v1/…
  • https://api.rete.toscana.it/C01/CPisa/sample-api/v1/…
  • https://api.rete.toscana.it/C02/CPisa/sample-api/v1/…

Al momento della richiesta di adesione ad un servizio, il richiedente può chiedere di accedere ad una API utilizzando un applicativo client preesistente compatibile con le modalità di accesso a quella API oppure richiedere la registrazione di un nuovo applicativo. Nel primo caso CART autorizza l’applicativo ad accedere alla API, nel secondo caso registra un nuovo applicativo e fornisce al richiedente le relative credenziali.

La prima modalità è tipicamente utilizzata quando la medesima applicazione ha bisogno di accedere a più API. È sempre possibile usare credenziali multiple per accedere ad API diverse, ma è da evitare per le inutili complicazioni introdotte nella gestione delle credenziali e nel monitoraggio degli accessi al servizio. È altrettanto da evitare, quando possibile, l’utilizzo delle medesime credenziali per l’accesso ad una API di più applicazioni. Ogni singola applicazione client deve essere registrata su CART alla prima richiesta di accesso, per poi ottenere eventuali autorizzazioni ulteriori in base alle successive necessità.

Qualunque sia la modalità utilizzata, al termine dell’iter di adesione l’applicazione client potrà accedere alle API utilizzando una delle tipologie di accesso previste:

  • HTTP Basic, modalità deprecata, ma ancora supportata per compatibilità con il passato. In questa modalità utenza e password sono fornite dalla gestione CART al referente dell’adesione.
  • HTTPS, in questo caso per l’accesso alle API è richiesta la client authentication HTTPS. L’archivio contenente la chiave privata e il certificato X509 è fornito da CART tramite una comunicazione sicura con il referente dell’adesione.
  • Token Authentication: in questo caso l’accesso all’API è gestito tramite bearer authentication. Il token deve essere rilasciato da una delle fonti di autenticazione riconosciute da Regione Toscana. Tipicamente il token viene ottenuto dal client tramite negoziazione OAUTH2 con gli authorization server di Regione Toscana.

Se la richiesta di adesione è riferita ad API che prevedono accesso tramite token, i token presentati dai client per l’accesso alla API dovranno avere il nome della API nel claim audience del token presentato per l’accesso, oltre ovviamente a tutti gli altri parametri previsti dalle politiche di accesso alla API (ad esempio: spid-level).