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

```bash
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](/it/guides/claves-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](/it/api/plans-and-limits/)) — e restituisce l'insieme EFFETTIVO di scope della
tua chiave, così non devi mai indovinarlo:

```bash
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ù.