API Key
Richiede il permesso di gestione delle chiavi API, incluso di default per gli amministratori del tenant e per il ruolo Super Admin.
Le chiavi API consentono ad applicazioni esterne di chiamare Askme AI senza login interattivo. Ogni chiave è associata al tenant, ha uno scope di permessi limitato e può essere ruotata o revocata in qualsiasi momento.
Prerequisiti
- Ruolo di amministratore o Super Admin, oppure un ruolo personalizzato con il permesso sulle API key.
- Un ruolo applicativo da associare alla chiave (i permessi della chiave coincidono con quelli del ruolo scelto, eventualmente ristretti tramite scope).
Generare una nuova chiave
Aprire la sezione Chiavi API
Dalla sidebar, selezionare Amministrazione → API Key. È visibile l'elenco delle chiavi già presenti nel tenant, con prefisso, ruolo, stato, ultimo utilizzo e scadenza.
Avviare la creazione
Selezionare Nuova chiave. Si apre il dialogo di creazione.
Compilare i campi
| Campo | Descrizione |
|---|---|
| Nome | Identificativo descrittivo della chiave (es. «Integrazione CRM produzione»), utile per riconoscere a quale integrazione appartiene |
| Ruolo | Insieme di permessi che la chiave può esercitare; è opportuno creare un ruolo dedicato con il minimo necessario invece di riutilizzare admin |
| Scope | Sottoinsieme puntuale di permessi del ruolo (es. agents.*), per restringere ulteriormente l'ambito della chiave |
| App di origine | Etichetta che identifica l'applicazione chiamante: askmechat, askmedesk, askmesign, hub, web-ui o altro valore concordato |
| Limiti di velocità | Richieste massime al minuto e al giorno |
| Scadenza | Data oltre la quale la chiave smette di funzionare; consigliata per pianificare la rotazione |
Salvare e copiare la chiave
Alla conferma, il sistema mostra la chiave in chiaro una sola volta.
La chiave in chiaro è visibile una sola volta. È necessario copiarla immediatamente e conservarla in un gestore di segreti: nel database restano solo hash e prefisso, quindi Askme AI non può restituirla in seguito. In caso di smarrimento, l'unica soluzione è la rotazione (vedi sotto).
Stati di una chiave
| Stato | Significato |
|---|---|
| Attiva | In uso, accetta richieste |
| Scaduta | Data di scadenza superata, richieste rifiutate |
| Revocata | Disattivata manualmente, richieste rifiutate |
Rotazione
La rotazione revoca la chiave esistente e ne emette una sostitutiva mantenendo nome, ruolo, scope, limiti e scadenza. La chiave in chiaro viene restituita una sola volta nella risposta.
Selezionare Ruota sulla riga della chiave: la nuova chiave viene mostrata nel dialogo. È necessario aggiornare subito l'integrazione, perché la chiave precedente smette di funzionare al momento della rotazione.
Una buona pratica è ruotare le chiavi almeno ogni 90 giorni e impostare una scadenza esplicita sulle chiavi a lungo termine.
Revoca
Selezionare Revoca per disattivare immediatamente una chiave. L'operazione è irreversibile: per ripristinare l'integrazione occorre crearne una nuova.
È opportuno revocare subito una chiave quando si sospetta una compromissione, quando l'integrazione associata è stata dismessa o quando cambia la responsabilità dell'integrazione.
Risultato atteso
La nuova chiave compare nell'elenco con stato Attiva, prefisso, ruolo, scope e limiti di velocità visibili; le richieste autenticate con la chiave sono attribuite all'app di origine indicata nelle dashboard di Monitoraggio.
Problemi comuni
| Problema | Causa probabile | Soluzione |
|---|---|---|
| La chiave restituisce errore di autorizzazione | Lo scope o il ruolo associato non include il permesso richiesto dalla chiamata | Rivedere il ruolo/scope della chiave o crearne una con permessi più ampi |
| Le richieste vengono rifiutate improvvisamente | La chiave è scaduta o è stata revocata | Verificare lo stato nell'elenco; se necessario generarne una nuova |
| Superato il limite di richieste | Il traffico dell'integrazione supera i limiti di velocità impostati | Aumentare i limiti configurati o distribuire le chiamate nel tempo |