Autenticazione

Ogni richiesta a /public/v1/* si autentica con l’header X-API-Key — mai con Authorization: Bearer, né con un cookie di sessione:

curl https://api.nuntius.chat/public/v1/leads \
  -H "X-API-Key: aa_TUA_CHIAVE_COMPLETA"

Una chiave si vede per intero una sola volta, quando la crei (guida Chiavi API, sezione 4); da quel momento, in qualsiasi elenco si vede solo il suo prefisso (aa_xxxxxxxx…).

Catalogo degli scope

Ogni risorsa ha due scope indipendenti — lettura e gestione (creare/aggiornare). Una chiave senza lo scope esatto richiesto dall’endpoint riceve 403 PERMISSION_DENIED, anche con il resto dei suoi permessi intatti:

Risorsa	Lettura	Gestione
Lead	tenant:leads.read	tenant:leads.manage
Contatti	tenant:contacts.read	tenant:contacts.manage
Conversazioni	tenant:conversations.read	tenant:conversations.manage
Appuntamenti	tenant:appointments.read	tenant:appointments.manage
Ticket	tenant:tickets.read	tenant:tickets.manage

GET /public/v1/me non richiede nessuno scope proprio — solo una chiave valida di un tenant con piano idoneo (vedi Piani e limiti) — e restituisce l’insieme EFFETTIVO di scope della tua chiave, così non devi mai indovinarlo:

curl https://api.nuntius.chat/public/v1/me -H "X-API-Key: aa_TUA_CHIAVE_COMPLETA"

Seleziona gli scope di cui hai bisogno nel passaggio “Personalizza” quando crei la chiave (guida delle chiavi API, sezione 7) — la selezione resta fissata da quel momento, non si amplia dopo: per aggiungere uno scope devi revocare la chiave e crearne una nuova.

Cosa una chiave non può fare mai

• Nulla al di fuori delle 5 risorse sopra. Non esiste una rotta pubblica per fatturazione, team, impostazioni, integrazioni, agenti IA o amministrazione — qualunque sia lo scope della chiave, quelle azioni semplicemente non hanno un endpoint sotto /public/v1.
• Vedere o toccare i dati di un altro tenant. Una chiave è legata a un solo tenant; un id di un altro tenant su qualsiasi rotta risponde 404, indistinguibile da “non esiste” (mai 403, che confermerebbe che esiste).
• Accedere all’interfaccia web della Piattaforma — la chiave autentica chiamate API, non il login di una persona.

Rotazione delle chiavi

Oggi non esiste un endpoint di rotazione atomica. Per ruotare una chiave: creane una nuova con gli stessi scope, aggiorna il segreto nella tua integrazione e poi revoca quella vecchia (guida delle chiavi API, sezione 9) — c’è una breve finestra con entrambe attive, senza invalidazione istantanea della vecchia alla creazione della nuova.

Origini consentite

allowed_origins (configurabile alla creazione della chiave) è una difesa contro l’abuso da browser — si controlla solo quando la richiesta porta l’header Origin. Una chiamata server-a-server, l’uso principale di questa API, di norma non lo invia e passa comunque anche con l’elenco ristretto: non trattarlo come il meccanismo di autenticazione, solo come un livello in più.