Chiavi API

Le chiavi API consentono ad applicazioni esterne di chiamare Askme AI senza login interattivo. Ogni chiave e' associata al tuo tenant, ha uno scope di permessi limitato e puo' essere revocata o ruotata in qualsiasi momento.

Generare una nuova chiave

1. Apri la sezione Chiavi API

Dal menu laterale scegli Amministrazione → Chiavi API. Trovi la lista delle chiavi gia' presenti nel tenant con prefisso, ruolo, stato, ultimo utilizzo e data di scadenza.

2. Avvia la creazione

Click sul pulsante + Nuova chiave in alto a destra. Si apre il dialog di creazione.

3. Compila i campi

Campo	Descrizione
Nome	Identificativo descrittivo della chiave, es. Integrazione CRM produzione. Aiuta a riconoscere a quale integrazione appartiene
Tipo	Piattaforma per chiavi standard (chiamate REST verso Askme AI). Provider solo per usi provider-side avanzati
Ruolo	Insieme di permessi che la chiave puo' esercitare. Crea un ruolo dedicato con il minimo necessario invece di usare il ruolo admin
Scopes	(Opzionale) sottoinsieme di permessi del ruolo per restringere ulteriormente
Scadenza	(Opzionale) data oltre la quale la chiave smette di funzionare. Consigliata per pianificare la rotazione
Rate limit RPM	(Opzionale) richieste massime al minuto
Rate limit RPD	(Opzionale) richieste massime al giorno

4. Salva e copia la chiave

Click su Crea. Il sistema mostra la chiave in chiaro nel formato amai_xxxxxxxx....

Chiave mostrata una sola volta

La chiave in chiaro e' visibile una sola volta. Copiala subito (icona di copia accanto al valore) e archiviala in un secret manager. Solo l'hash e il prefisso restano nel database: Askme AI non puo' restituirti la chiave in chiaro in seguito.

Se perdi la chiave, l'unica strada e' rotearla (vedi sotto).

5. Verifica nella lista

Dopo la chiusura del dialog, la nuova chiave compare nella lista con prefisso amai_xxxxxxx, stato Attiva, ruolo, scopes e rate limit.

Stati di una chiave

Stato	Significato
Attiva	In uso, accetta richieste
Scaduta	Data di scadenza superata, richieste rifiutate
Revocata	Disattivata manualmente, richieste rifiutate

Usare la chiave

Le richieste autenticate via API key devono includere l'header X-Api-Key:

X-Api-Key: amai_<la_tua_chiave>

Le chiavi hanno sempre il prefisso amai_ seguito da una stringa opaca. Il prefisso è anche la sola parte mostrata nella lista dopo la creazione (per identificare la chiave senza esporne il valore completo).

Header aggiuntivi

Header	Obbligatorio	Descrizione
X-Source-App	Sì	Identifica l'applicazione chiamante. Lista chiusa: askmechat, askmedesk, api_direct (integrazioni custom), askmeai, internal. Per integrazioni esterne via API key il valore tipico e' api_direct. Valori al di fuori della lista vengono rifiutati
X-External-Id	Opzionale	Identificatore opaco del sistema esterno (ticket ID, ordine ID, ...). Propagato in ogni record di costo prodotto dalla richiesta. Massimo 255 caratteri. Utile per correlazione end-to-end con i log del chiamante

Esempio cURL

curl -X POST https://ai.askme.it/api/v2/chat \
  -H "X-Api-Key: amai_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "X-Source-App: api_direct" \
  -H "X-External-Id: req-12345" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": 12,
    "message": "Buongiorno, vorrei informazioni sul prodotto X.",
    "stream": false
  }'

Per ricevere la risposta in streaming (SSE), imposta "stream": true nel body — l'endpoint resta POST /api/v2/chat e risponde con Content-Type: text/event-stream.

Rotazione

La rotazione e' un'operazione atomica che revoca la chiave esistente e ne crea una sostitutiva con le stesse impostazioni (scopes, rate limit, scadenza). La chiave in chiaro viene restituita una sola volta nella risposta.

Click su Ruota sulla riga della chiave: la nuova chiave ti viene mostrata nel dialog. Aggiorna immediatamente l'integrazione che la utilizza, perche' la vecchia chiave smette di funzionare al momento della rotazione.

Pianifica la rotazione

Buona pratica e' ruotare le chiavi almeno ogni 90 giorni. Imposta una scadenza esplicita sulle chiavi a lungo termine per ricevere un alert prima della scadenza.

Revoca

Click su Revoca per disattivare immediatamente una chiave. La revoca e' irreversibile: per riattivare l'integrazione devi crearne una nuova.

Revoca subito una chiave se:

• Sospetti compromissione (commit accidentale in repo pubblico, log esposti, ecc.)
• L'integrazione associata e' stata dismessa
• Il dipendente che la gestiva non lavora piu' sul progetto

Best practice

• Una chiave per integrazione — non condividere la stessa chiave fra applicazioni diverse: cosi' una compromissione si limita a un solo punto
• Rate limit conservativo — imposta sempre un limite congruo con il traffico atteso
• Scopes minimi — assegna alla chiave un ruolo con solo i permessi indispensabili (es. chat.read + chat.write per un chatbot pubblico)
• Secret manager — non salvare mai la chiave in .env committati o in codice sorgente; usa un vault (AWS Secrets Manager, HashiCorp Vault, ecc.)
• Header X-Source-App — popolalo sempre: ti aiuta a distinguere il traffico nelle dashboard di monitoraggio
• Rotazione periodica — calendarizza una rotazione almeno trimestrale