Chiavi API
Pagina Impostazioni > Chiavi API, nel gruppo API. Compare solo se la capacità Accesso API è attiva per l'organizzazione (vedere Capacità) e richiede il permesso di consultazione delle chiavi API, incluso nel ruolo di amministratore. Dal menu laterale si apre con la voce API del gruppo Impostazioni.
Le chiavi API consentono ad applicazioni esterne di chiamare Askme AI senza accesso interattivo. Ogni chiave appartiene all'organizzazione e può usare soltanto le funzioni scelte alla sua creazione, che si possono modificare in seguito; la chiave si può inoltre ruotare o revocare. A una chiave non si associa un ruolo: ciò che la chiave può fare dipende esclusivamente dalle sue funzioni.
Prerequisiti
- Capacità Accesso API attiva per l'organizzazione.
- Ruolo di amministratore, oppure un ruolo personalizzato con i permessi sulle chiavi API. Creazione, modifica e revoca sono permessi distinti e la console mostra solo i comandi consentiti; la rotazione richiede il permesso di creazione.
L'elenco delle chiavi
L'elenco si filtra con i campi Cerca e Stato. Sulla riga di ogni chiave sono disponibili i comandi Modifica, Ruota ed Elimina. Una chiave revocata non compare nell'elenco predefinito e si consulta scegliendo Revocata nel filtro Stato.
| Colonna | Contenuto |
|---|---|
| Nome chiave | Nome descrittivo dell'integrazione |
| Chiave | Parte iniziale della chiave, utile per riconoscerla senza esporla |
| App di origine | Applicazione che usa la chiave |
| Stato | Attiva oppure Revocata |
| Ultimo utilizzo | "usata oggi", "usata ieri" oppure il numero di giorni trascorsi; vuota se la chiave non è mai stata usata. Il valore si aggiorna periodicamente, non a ogni chiamata |
| Scadenza | Data in cui la chiave smette di funzionare, evidenziata quando mancano quattordici giorni o meno; vuota per una chiave senza scadenza |
| Creato il | Data e ora di creazione |
Creare una chiave
- In Impostazioni > Chiavi API, selezionare Nuova chiave.
- Compilare i campi del dialog (vedere la tabella seguente).
- Selezionare Crea.
- Nel dialog Chiave API generata, selezionare Copia, conservare la chiave in un archivio sicuro e selezionare Chiudi.
| Campo | Descrizione |
|---|---|
| Nome chiave | Obbligatorio. Nome che identifica l'integrazione, per esempio «Integrazione CRM produzione» |
| Funzioni della chiave | Funzioni che la chiave può usare, raggruppate per area (per esempio Agenti, Basi di conoscenza, Conversazioni, Analisi documenti, Monitoraggio); ogni gruppo si espande e indica quante funzioni sono selezionate. Per impostazione predefinita è selezionata la casella Tutte le funzioni. È necessario selezionare almeno una funzione (vedere Funzioni della chiave) |
| Scadenza (giorni) | Durata della chiave, da 1 a 365 giorni. Se il campo resta vuoto la chiave non scade |
| App di origine | Applicazione che userà la chiave: Generale (valore predefinito), Askme Chat, Askme Desk, Askme Sign, Askme Hub, Portale assistenza o Console web. Nel monitoraggio le chiamate effettuate con la chiave sono raggruppate sotto questa applicazione. Non si cambia dopo la creazione |
Il dialog Chiave API generata è l'unico momento in cui la chiave è visibile in chiaro: Askme AI non la conserva e non può mostrarla di nuovo. In caso di smarrimento occorre ruotare la chiave (vedere Ruotare una chiave).
Funzioni della chiave
Il selettore Funzioni della chiave stabilisce che cosa l'integrazione può fare. Per un'integrazione è preferibile togliere la casella Tutte le funzioni e selezionare soltanto le funzioni necessarie, per esempio Avviare conversazioni e Consultare gli agenti per un'applicazione che si limita a conversare con un agente.
La casella Tutte le funzioni comprende ogni funzione di prodotto, incluse quelle che saranno aggiunte in futuro, ma non comprende la sezione Gestione di utenti, ruoli e chiavi API. Le voci di questa sezione vanno selezionate una per una: una chiave che le possiede può creare utenti, assegnare ruoli e generare altre chiavi API, cioè nuove credenziali di accesso, per cui conviene concederle solo quando l'integrazione ne ha davvero bisogno.
Nelle API lo stesso insieme corrisponde al valore *: copre le funzioni di prodotto ma non la gestione di utenti, ruoli e chiavi API (vedere Autenticazione).
Modificare una chiave
Il comando Modifica apre il dialog Modifica chiave API, che interviene sulle impostazioni della chiave senza cambiarne il valore. Una chiave revocata non può più essere modificata.
| Campo | Descrizione |
|---|---|
| Nome chiave | Nome descrittivo, obbligatorio |
| Funzioni della chiave | Lo stesso selettore della creazione. Se la chiave contiene funzioni che non esistono più, il dialog le elenca nel riquadro Funzioni non più valide: vanno tolte con Rimuovi prima di salvare una modifica delle funzioni |
| Limite richieste al minuto | Numero massimo di richieste al minuto. Se il campo è vuoto, la chiave non ha un limite proprio |
| Limite richieste al giorno | Numero massimo di richieste al giorno. Se il campo è vuoto, la chiave non ha un limite proprio |
| Scadenza | Data, scelta dal calendario, in cui la chiave smette di funzionare; deve essere successiva al momento della modifica |
Una richiesta che supera uno dei limiti viene rifiutata con l'errore 429, che indica dopo quanti secondi riprovare.
Ruotare una chiave
La rotazione revoca la chiave esistente e ne emette una nuova che mantiene nome, app di origine, funzioni e limiti di richieste. Se la chiave aveva una scadenza, la nuova chiave ha la stessa durata, calcolata a partire dal momento della rotazione. Una chiave scaduta o revocata non si può ruotare: a una chiave scaduta si assegna una nuova Scadenza con Modifica.
- Selezionare Ruota sulla riga della chiave.
- Nel dialog di conferma Ruota Chiave API, selezionare Ruota.
- Copiare la nuova chiave dal dialog Chiave API generata.
- Aggiornare subito l'integrazione: la chiave precedente smette di funzionare al momento della rotazione.
È buona pratica ruotare periodicamente le chiavi e impostare una scadenza anche sulle chiavi destinate a durare a lungo.
Revocare una chiave
La console non ha un comando Revoca: la revoca si esegue con Elimina.
- Selezionare Elimina sulla riga della chiave.
- Confermare nel dialog Elimina Chiave API.
La chiave viene revocata immediatamente: le richieste che la usano sono rifiutate, la chiave non può più essere modificata e non compare più nell'elenco predefinito. L'operazione non si annulla; per ripristinare l'integrazione occorre creare una nuova chiave. La revoca è registrata nel Registro attività.
È opportuno revocare subito una chiave quando se ne sospetta la compromissione, quando l'integrazione è stata dismessa o quando ne cambia il responsabile.
Risultato atteso
La nuova chiave compare nell'elenco con stato Attiva, la parte iniziale della chiave e l'app di origine indicata; dopo il primo utilizzo la colonna Ultimo utilizzo si aggiorna.
Problemi comuni
| Problema | Causa probabile | Soluzione |
|---|---|---|
| La voce Chiavi API non compare | Capacità Accesso API non attiva, oppure ruolo senza il permesso di consultazione | Verificare la capacità in Capacità e i permessi del ruolo |
| La chiave restituisce un errore di autorizzazione | Le funzioni della chiave non includono quella richiesta; le funzioni di gestione di utenti, ruoli e chiavi API non sono comprese in Tutte le funzioni | Aggiungere la funzione con Modifica |
| Le richieste vengono rifiutate improvvisamente | La chiave è scaduta o è stata revocata | Controllare la colonna Scadenza: a una chiave scaduta si assegna una nuova scadenza con Modifica; una chiave revocata va sostituita con una nuova |
| Le richieste ricevono l'errore 429 | Il traffico supera i limiti di richieste impostati sulla chiave | Attendere il tempo indicato nella risposta, aumentare Limite richieste al minuto o Limite richieste al giorno con Modifica, oppure distribuire le chiamate nel tempo |
| Il comando Ruota non riesce | La chiave è scaduta | Assegnare una nuova Scadenza con Modifica |
| Una chiave eliminata non è più in elenco | L'eliminazione revoca la chiave, che esce dall'elenco predefinito | Comportamento previsto |