L'utilizzo delle API è riservato a clienti, partner o soggetti autorizzati. Per poter utilizzare le API PEOPLELINK è necessario creare una o più chiavi di accesso, ognuna composta da una serie di informazioni e configurazioni tecniche necessarie sia a tracciare gli utilizzatori e il motivo della creazione, sia per applicare configurazioni e/o limitazioni di accesso.
Tramite la funzionalità Chiavi di accesso per le API, presente nel modulo ADVANCED, puoi creare e gestire tutte le chiavi di accesso di cui necessiti.
Esempio: potresti voler creare una chiave di accesso da utilizzare su un software terzo per la sincronizzazione dei soli dati del timesheet, e un'altra chiave di accesso per integrare unicamente le unità organizzative con un differente servizio aziendale.
L'accesso a questa funzionalità è gestita, al pari di tutte le altre funzionalità di PEOPLELINK, ovvero tramite i Ruoli autorizzativi.
Ti consigliamo di prestate la massima attenzione agli operatori a cui fornisci l'accesso, sia in lettura sia in scrittura.
Creare una nuova chiave di accesso alle API
Utilizza il pulsante Gestisci - Crea per avviare la procedura di creazione di una nuova chiave di accesso. La procedura di creazione è composta da due fasi distinte.
La prima fase prevede la compilazione delle informazioni fondamentali, ovvero lo username e la password da utilizzare per la richiesta del Token ACS oltre ai riferimenti tecnici.
Lo Userame ha una lunghezza minima di 10 caratteri, fino ad un massimo di 20 e deve essere univoco a livello globale.
La Password è sempre e obbligatoriamente generata da PEOPLELINK, ma può essere rigenerata più volte prima di essere salvata.
La password viene criptata e protetta al momento del salvataggio e non potrà essere recuperata in nessun modo. Va quindi copiata con l'apposito tasto alla destra della casella di testo e memorizzarla in un luogo sicuro prima di salvare l'utenza.
La descrizione, ovvero il motivo per cui viene creata la chiave di accesso, e i dati del referente sono obbligatori.
Il rate limit è fisso e i campi sono sempre disabilitati. I valori vengono ereditati dalle policy globali di PEOPLELINK. Per approfondimenti su cosa è e come funziona un rate limit fare riferimento ai Concetti di base.
Una volta che tutti i campi sono compilati si può procedere al salvataggio utilizzando il pulsante Salva. A seguire, utilizzando il pulsante Gestisci - Modifica, potrai avviare la modifica della chiave di accesso appena creata al fine procedere con la fase 2, ovvero l'inizializzazione delle ApiKey di lettura e/o scrittura, insieme ad eventuali limitazioni specifiche.
Le API di PEOPLELINK prevedono una differenziazione tra gli endpoint che consentono l'accesso in lettura rispetto agli endpoint di scrittura. Per generare la rispettiva ApiKey è necessario cliccare sul pulsante Genera Key in corrispondenza della rispettiva casella di testo. L'ApiKey può essere rigenerata più volte, ma tutte le eventuali versioni precedenti vengono annullate e sostituite sempre da quella nuova.
Di default, tutti gli endpoint sono abilitati per essere utilizzati. E' possibile applicare delle restrizioni agli endpoint abilitati sulla specifica chiave di accesso che si sta modificando utilizzando i dropdown Endpoint abilitati in lettura ed Endpoint abilitati in scrittura per selezionare cosa può essere utilizzato. Per indentificare cosa fa ogni endpoint e quali sono le sue caratteristiche, fare riferimento allo swagger.
Nel caso in cui siano abilitati, in lettura, uno o più endpoint che operano sugli eventi anagrafici, sarà obbligatorio anche indicare un Profilo amministrativo degli eventi anagrafici, il cui scopo è quello di applicare delle limitazioni ai dati anagrafici che possono essere letti nelle API (es. dati retributivi, indirizzi, formazione, visite mediche, etc.). Nel caso non vuoi applicare nessuna limitazione, dovrai obbligatoriamente selezionare la voce Non applicare nessun Profilo amministrativo degli eventi anagrafici.
Un ulteriore limitazione che puoi applicare alle chiavi di accesso alle API è relativa agli indirizzi IP del chiamante. Il campo IP Whitelist ti consente di indicare gli indirizzi IP abilitati a chiamare gli endpoint associati a questa chiave di accesso. Puoi indicare singoli indirizzi o range di IP, sia in formato IPV4 che IPV6.
Una volta che tutti i campi sono compilati si può procedere al salvataggio utilizzando il pulsante Salva.
Modificare le limitazioni e rigenerare le ApiKey di una chiave di accesso
Per modificare le limitazioni oppure per rigenerare le ApiKey di una chiave di accesso alle API premi sul pulsante Gestisci - Modifica.
Lo Username e la descrizione non sono mai modificabili, mentre la password non è mai visibile dopo che la chiave di accesso è stata creata e salvata.
Tutte le altre configurazioni, ad eccezione del rate limit, sono modificabili e rigenerabili in qualsiasi momento. Le regole e le logiche di funzionamento sono le stesse indicate nella fase della creazione di un nuova chiave di accesso.
Modificare la password di una chiave di accesso
Puoi modificare la password di una chiave di accesso alle API rigenerandola.
Così come avviene in fase di creazione di una nuova chiave di accesso, la Password è sempre e obbligatoriamente generata da PEOPLELINK, ma può essere rigenerata più volte prima di essere salvata.
La password viene criptata e protetta al momento del salvataggio e non potrà essere recuperata in nessun modo. Va quindi copiata con l'apposito tasto alla destra della casella di testo e memorizzarla in un luogo sicuro prima di salvare il cambio password.
