Autenticazione

Le API di Askme AI utilizzano API key come unico canale di autenticazione per le integrazioni. Ogni richiesta deve trasportare una chiave valida nell'header X-Api-Key.

Generazione della API key

Le chiavi si generano dalla console amministrativa del proprio tenant nella sezione Amministrazione → API Keys:

Accedi come amministratore del tenant.
Vai su Amministrazione → API Keys.
Clicca Genera nuova chiave, assegna un nome descrittivo (es. integrazione-crm-prod), un ruolo che definisce gli scope e una eventuale data di scadenza.
Copia il valore mostrato — viene presentato una sola volta: dopo la chiusura del dialog non sarà più recuperabile.

Guida estesa con screenshot: Manuale → API Keys.

Conservazione

Le API key concedono l'accesso ai dati del tenant. Conservale in un secret manager (HashiCorp Vault, AWS Secrets Manager, variabili d'ambiente cifrate). Non includerle in repository di codice o nel frontend.

Formato della chiave

Tutte le chiavi hanno il prefisso amai_ seguito da una stringa opaca:

amai_3f9d8c1e0a4b2f7d6c5a8e9b3f1d2c4a8e9b3f1d2c4a8e9b

Nelle interfacce di gestione e nei log viene mostrato solo il prefisso amai_xxxxxxx (12 caratteri totali) per identificare la chiave senza esporne il valore.

Header di autenticazione

Tutte le richieste alle API REST devono includere:

X-Api-Key: amai_<la-tua-api-key>

Esempio cURL

curl -X GET "https://ai.askme.it/api/v2/agents" \
  -H "X-Api-Key: amai_3f9d8c1e0a4b2f7d6c5a8e9b3f1d2c4a8e9b3f1d2c4a8e9b" \
  -H "Content-Type: application/json"

Esempio Python (httpx)

import httpx

API_KEY = "amai_3f9d8c1e0a4b2f7d..."
BASE = "https://ai.askme.it/api/v2"

client = httpx.Client(
    base_url=BASE,
    headers={"X-Api-Key": API_KEY},
    timeout=30.0,
)

resp = client.get("/agents")
resp.raise_for_status()
print(resp.json())

Esempio Node.js (fetch)

const API_KEY = process.env.ASKMEAI_API_KEY;
const BASE = 'https://ai.askme.it/api/v2';

const resp = await fetch(`${BASE}/agents`, {
  headers: {
    'X-Api-Key': API_KEY,
    'Content-Type': 'application/json',
  },
});

if (!resp.ok) {
  throw new Error(`API error ${resp.status}: ${await resp.text()}`);
}

const data = await resp.json();
console.log(data);

Header opzionali consigliati

Header	Obbligatorio	Descrizione
`X-Api-Key`	Sì	Chiave nel formato `amai_<key>`
`Content-Type`	Sì sui POST/PUT/PATCH	`application/json`
`X-Source-App`	Sì	Identifica l'applicazione chiamante. Lista chiusa di valori ammessi (vedi sotto)
`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

Valori ammessi per `X-Source-App`

Valore	Quando usarlo
`askmechat`	Chiamate provenienti da Askme Chat
`askmedesk`	Chiamate provenienti da Askme Desk
`api_direct`	Integrazione custom del cliente che chiama direttamente le API REST
`askmeai`	Solo applicazioni interne della console Askme AI (riservato)
`internal`	Solo chiamate inter-servizio della piattaforma (riservato)

Per integrazioni esterne via API key il valore tipico è api_direct. Valori al di fuori della lista vengono rifiutati.

Esempio richiesta completa

curl -X POST "https://ai.askme.it/api/v2/chat" \
  -H "X-Api-Key: amai_3f9d8c1e..." \
  -H "Content-Type: application/json" \
  -H "X-Source-App: api_direct" \
  -H "X-External-Id: ticket-92831" \
  -d '{
    "agent_id": 12,
    "message": "Riassumi la procedura di reso",
    "stream": false
  }'

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

Permessi e scope

Le API key ereditano il ruolo associato in fase di generazione. Il ruolo determina gli scope (insiemi di permessi) che la chiave può esercitare. Per integrazioni che richiedono accessi differenziati è consigliata la creazione di chiavi separate con ruoli minimi.

Multi-tenancy

L'header X-Tenant-ID non è richiesto: la tenancy è risolta dalla chiave stessa, univocamente associata a un tenant in fase di generazione.

Errori comuni

Codice HTTP	Significato	Causa tipica
`401 Unauthorized`	`X-Api-Key header required`	Header `X-Api-Key` non inviato
`401 Unauthorized`	`Invalid API key format`	Valore non con prefisso `amai_`
`401 Unauthorized`	`Invalid API key`	Chiave revocata, scaduta o errata
`403 Forbidden`	Permesso insufficiente	Il ruolo della chiave non copre l'operazione richiesta
`429 Too Many Requests`	Rate limit raggiunto	Limite RPM/RPD configurato sulla chiave superato

Rate limit

Ogni chiave può avere limiti dedicati:

rate_limit_rpm — richieste al minuto
rate_limit_rpd — richieste al giorno

Quando il limite è raggiunto, il servizio risponde 429 con header Retry-After (secondi).

Rotazione e revoca

Rotazione — operazione atomica che revoca la chiave esistente e ne crea una sostitutiva con le stesse impostazioni (scope, rate limit, scadenza). La nuova chiave in chiaro viene mostrata una sola volta.
Revoca — disattiva immediatamente la chiave; le richieste in volo vengono rifiutate al successivo controllo. Operazione irreversibile.

Best practice

Una API key per integrazione (mai una chiave condivisa fra ambienti).
Imposta una scadenza realistica (90 / 180 giorni) e pianifica la rotazione.
Monitora l'utilizzo nelle dashboard Monitoring → Costi filtrando per source_app.
In caso di sospetta compromissione, revoca immediatamente e indaga gli accessi via audit log.

Generazione della API key​

Formato della chiave​

Header di autenticazione​

Esempio cURL​

Esempio Python (httpx)​

Esempio Node.js (fetch)​

Header opzionali consigliati​

Valori ammessi per X-Source-App​

Esempio richiesta completa​

Permessi e scope​

Multi-tenancy​

Errori comuni​

Rate limit​

Rotazione e revoca​

Best practice​