> ## Documentation Index
> Fetch the complete documentation index at: https://www.notifuse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Admin e API Key

> Invita gli admin e crea API Key limitate alle parti del workspace che servono loro, cambia i loro permessi in qualsiasi momento e scopri cosa consente ciascun permesso.

![Impostazioni, Team e API Key: i membri, un invito in attesa e due API Key](https://www.notifuse.com/docs/assets/screenshots/api_key.png)

## Gestione degli admin

### Invitare gli admin

- Solo il proprietario del workspace può invitare nuovi admin.
- Scegli tu i permessi che l'invito conferisce, e puoi cambiarli in seguito.
- Gli inviti vengono spediti via email.

Il proprietario ha tutti i permessi e non può essere limitato. Tutti gli altri, sia gli admin in carne e ossa sia le API Key, hanno un insieme di permessi scelto da te.

### Permessi

> [!NOTE]
>
> **Self-hosted: per salvare un insieme di permessi diverso dall'accesso completo serve una [chiave di licenza](https://www.notifuse.com/it/docs/self-hosting/licence.md).** Vale per impostare i permessi di un membro, per invitare con un insieme limitato e per creare un'API Key con un ambito limitato. Senza chiave, i nuovi membri e le nuove chiavi ricevono l'accesso completo. I permessi già concessi restano applicati in ogni stato della licenza, e rimuovere un membro è sempre possibile, perché è così che si revoca una chiave trapelata. Notifuse Cloud include i permessi granulari dal piano Starter in su ([dettagli](https://www.notifuse.com/it/docs/self-hosting/licence.md#on-notifuse-cloud)).

Un permesso è una coppia di interruttori su un'area del workspace: **lettura** e **scrittura**. La scrittura non implica la lettura, ed entrambi sono spenti finché non vengono concessi. La barra laterale della console mostra una sezione quando il membro ha almeno uno dei due interruttori sulla sua area.

Puoi cambiare i permessi di un membro dalla pagina Team e API Key in qualsiasi momento. La modifica vale dalla sua richiesta successiva.

## Gestione delle API Key

### Creare le API Key

- Solo il proprietario del workspace può creare un'API Key.
- Scegli i permessi della chiave quando la crei, oppure concedi tutto.
- Il token viene mostrato una sola volta, alla creazione della chiave.

![I permessi di un'API Key, con gli interruttori di lettura e scrittura per ogni risorsa](https://www.notifuse.com/docs/assets/screenshots/api_key_permissions.png)

Una chiave creata senza scegliere alcun permesso ha accesso completo al workspace. Le chiavi create prima dell'arrivo dei permessi limitati si comportano allo stesso modo finché non le restringi. Una chiave creata con tutti i permessi spenti può comunque autenticarsi e raggiungere i pochi endpoint che nessun permesso controlla: `/api/workspaces.list` restituisce il record del workspace a cui appartiene la chiave (le sue impostazioni, le etichette dei campi personalizzati e i blocchi di template riutilizzabili salvati lì), con le credenziali dei provider oscurate. Tutto ciò che compare nella tabella qui sotto le è precluso.

Dai a ogni integrazione la sua chiave, con i permessi più ristretti di cui ha bisogno. Una chiave che invia solo email transazionali richiede solo la scrittura su Transazionale (vedi [API transazionale](https://www.notifuse.com/it/docs/features/transactional-api.md)). [Zapier](https://www.notifuse.com/it/docs/integrations/zapier.md) imposta un ambito suo: collegarlo da **Impostazioni** → **Integrazioni** crea una chiave con lettura e scrittura su Subscription Webhook, Contatti e Liste, più la lettura su Segmenti.

Il prefisso che scegli diventa l'indirizzo email API della chiave e il nome utente del bridge SMTP. Accetta lettere minuscole, cifre, trattini e trattini bassi, fino a 64 caratteri, e si può usare una sola volta per installazione di Notifuse.

### Cambiare l'ambito di una chiave

Puoi allargare o restringere una chiave esistente in qualsiasi momento dalla pagina Team e API Key. La modifica vale dalla richiesta successiva della chiave. **Il token non cambia**, quindi non devi riemettere nulla né aggiornare alcuna integrazione.

### Sicurezza

- Copia e conserva il token appena la chiave viene creata.
- Un token perso non si può recuperare: crea una nuova chiave.
- Tutte le chiamate API devono usare HTTPS.

Quando una chiave viene rifiutata, l'API risponde `403` e indica l'area mancante (`contacts`, `webhook_subscriptions` e così via) e l'interruttore mancante. Un `403` dovuto a una quota non indica né l'una né l'altro, quindi è facile distinguere i due casi.

## Revocare una chiave

> [!WARNING]
>
> Rimuovere la chiave è l'unico modo per revocarla, ed è un'operazione distruttiva: il token resta valido finché
> la chiave non viene rimossa, e una chiave rimossa non si può ripristinare né riemettere. Ogni integrazione che la usa
> smette di funzionare nel momento in cui la rimuovi.

Tieni presenti questi due punti prima di un incidente:

- **Restringere una chiave non la revoca.** Una chiave privata di tutti i permessi si autentica ancora e conserva l'accesso che nessun permesso controlla. Restringi una chiave per contenerla, non per eliminarla.
- **Non puoi sapere quale chiave è trapelata.** Le chiavi non hanno una data di ultimo utilizzo né un log delle richieste per chiave: se sospetti che un token sia stato esposto ma non hai il token stesso, Notifuse non può dirti di quale chiave si tratta. Con più chiavi in uso, l'unica risposta sicura è rimuoverle tutte, crearne di nuove e aggiornare ogni integrazione.

Non sempre rimuovi una chiave dalla pagina Team e API Key: eliminare una connessione [Zapier](https://www.notifuse.com/it/docs/integrations/zapier.md) da **Impostazioni** → **Integrazioni** rimuove la chiave che aveva creato, ed eliminare un workspace rimuove tutte le sue chiavi. Anche rimuovere da Team e API Key la chiave di una connessione Zapier la revoca, ma lascia la scheda della connessione, che punta a una chiave che non esiste più.

Tieni quindi poche chiavi, dai a ciascuna un prefisso che nomina il sistema che la usa e preferisci chiavi ristrette: così una fuga di dati ti costa un'integrazione e non l'intero workspace.

## Cosa consente ciascun permesso

> [!NOTE]
>
> Quando una release introduce un nuovo permesso, i membri e le API Key esistenti lo ricevono con
> l'aggiornamento. Una chiave che hai ristretto di proposito si allarga quindi alla nuova area e resta così
> finché non la restringi di nuovo: ricontrolla le chiavi limitate dopo ogni aggiornamento. Fa eccezione una chiave
> con _tutti_ i permessi spenti, che l'aggiornamento lascia com'è.
>
> **La lettura su Registri di audit è la seconda eccezione**, e l'unico permesso che funziona così: non viene
> mai aggiunto con un aggiornamento e non fa parte dell'accesso completo. Concedilo solo alle persone e alle chiavi
> che devono poter leggere l'indirizzo email, l'indirizzo IP e le azioni rifiutate di ogni collega.

Nella console, clicca il nome di un permesso nella matrice per vedere gli endpoint che controlla e cosa fa ciascuno. La tabella qui sotto li riassume.

| Permesso                 | La lettura consente                                                                                                                                                                                                                                                                                                        | La scrittura consente                                                                                                                                                                                                                                                         |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Contatti**             | Vedere i contatti con i loro profili completi, la loro timeline e gli eventi personalizzati registrati su di loro. Serve anche per elencare gli indirizzi di una lista o di un segmento e per impostare `cc` o `bcc` in un invio transazionale                                                                             | Creare e aggiornare contatti, **eliminarli**, **sovrascrivere in blocco ogni campo** con un'importazione CSV o via API, e registrare eventi personalizzati                                                                                                                    |
| **Segmenti**             | Vedere i segmenti con le loro definizioni e lo stato delle loro attività di costruzione. Per l'anteprima di un segmento, o per elencare i contatti che corrispondono, serve anche la lettura su Contatti                                                                                                                   | Creare, modificare, eliminare e ricostruire segmenti, e avviare, azzerare o eliminare le loro attività di costruzione                                                                                                                                                         |
| **Liste**                | Vedere le liste, le loro impostazioni e il numero di iscritti. Per elencare i membri di una lista serve anche la lettura su Contatti                                                                                                                                                                                       | Creare, modificare ed eliminare liste, e **iscrivere un indirizzo a qualsiasi lista, pubblica o no, creando o sovrascrivendo il record di quel contatto nella stessa chiamata**. Per cambiare o rimuovere un'iscrizione esistente serve anche la scrittura su Contatti        |
| **Template**             | Vedere i template in tutte le lingue e i blocchi di template riutilizzabili, e compilare un template con dati di prova. Insieme alla scrittura su Transazionale, serve anche per inviare un'email di prova e per creare o modificare una notifica transazionale                                                            | Creare, modificare ed eliminare template e blocchi riutilizzabili. Modificare un blocco non cambia i template che lo contengono già                                                                                                                                           |
| **Blog**                 | Vedere categorie, articoli comprese le bozze non pubblicate, e versioni del tema compresi i loro script                                                                                                                                                                                                                    | Creare, modificare, eliminare, pubblicare e ritirare articoli e categorie; **pubblicare un tema**; e cambiare le impostazioni del blog, compresa l'attivazione o la disattivazione del blog                                                                                   |
| **Broadcast**            | Vedere i broadcast, la loro configurazione, i risultati dei test A/B e lo stato delle loro attività di invio. Le statistiche di consegna dipendono dalla lettura su Cronologia Messaggi                                                                                                                                    | Creare e modificare broadcast, aggiornare e provare i data feed, e programmare, **inviare a tutto il pubblico**, mettere in pausa, riprendere, annullare ed eliminare un broadcast, scegliere il vincitore del test A/B, e avviare o azzerare l'attività di invio sottostante |
| **Transazionale**        | Vedere le definizioni delle notifiche transazionali                                                                                                                                                                                                                                                                        | Crearle, modificarle ed eliminarle, e inviare email reali: via API, via bridge SMTP e come prova di un template. Provare un provider email resta riservato al proprietario. Vedi [le regole di invio](#transactional-sending-and-contacts) più sotto                          |
| **Automazioni**          | Vedere le automazioni, la configurazione completa dei loro nodi compresi gli URL e i segreti bearer dei nodi webhook, e il percorso di un singolo contatto indicato per nome in un flusso                                                                                                                                  | Creare, modificare ed eliminare automazioni, e attivarle o metterle in pausa                                                                                                                                                                                                  |
| **Cronologia Messaggi**  | Vedere i messaggi inviati con gli indirizzi dei destinatari e i dati usati per comporli, e i conteggi di consegne, aperture, click, bounce e click per link di un broadcast                                                                                                                                                | **Niente: oggi questo verbo non controlla nulla**                                                                                                                                                                                                                             |
| **Web Analytics**        | Vedere le statistiche del sito, le annotazioni disegnate su quei grafici e l'avanzamento dell'importazione storica                                                                                                                                                                                                         | Creare, modificare ed eliminare annotazioni, avviare e annullare l'importazione storica, e cambiare le impostazioni di web analytics (domini consentiti, filtri, etichette delle dimensioni personalizzate e identificazione dei link nelle email)                            |
| **Subscription Webhook** | Elencare le subscription e aprirne una, e leggere il log delle consegne con il payload di ogni evento e la risposta dell'endpoint. Il segreto di firma è nascosto a tutti tranne che al proprietario                                                                                                                       | Creare, modificare, eliminare, attivare e disattivare subscription, e lanciare una consegna di prova                                                                                                                                                                          |
| **Eventi Webhook**       | Vedere le callback grezze che i tuoi provider email rimandano, con gli indirizzi dei destinatari e la diagnostica dei provider                                                                                                                                                                                             | **Niente: oggi questo verbo non controlla nulla**                                                                                                                                                                                                                             |
| **Registri di audit**    | Leggere il [registro di audit](https://www.notifuse.com/it/docs/features/audit-logs.md) ed esportarlo: chi ha fatto cosa nel workspace, con l'indirizzo email di chi ha agito, l'indirizzo IP da cui proveniva e le azioni che gli sono state rifiutate. **Mai concesso dall'"accesso completo"** (vedi la nota qui sopra) | **Niente: oggi questo verbo non controlla nulla.** Le voci le scrive la piattaforma, e la conservazione è un'impostazione riservata al proprietario                                                                                                                           |
| **LLM**                  | **Niente: oggi questo verbo non controlla nulla**                                                                                                                                                                                                                                                                          | Usare l'assistente IA                                                                                                                                                                                                                                                         |
| **Workspace**            | Leggere il record del workspace e le sue impostazioni, e vedere tutto il team: membri, proprietari, API Key e inviti in attesa. Senza questo permesso l'elenco del team mostra solo la tua riga invece di essere rifiutato                                                                                                 | Rinominare le etichette dei campi personalizzati dei contatti del workspace, e avviare, azzerare o eliminare un'attività di sincronizzazione di un'integrazione. **Nient'altro** (vedi sotto)                                                                                 |

Due famiglie di endpoint sono condivise e controllano il permesso che corrisponde alla richiesta: `/api/analytics.query` controlla il permesso di ogni schema che interroghi, e `/api/tasks.*` controlla il permesso del tipo di attività (Segmenti per la costruzione dei segmenti, Broadcast per gli invii, Web Analytics per le importazioni storiche, Workspace per le sincronizzazioni delle integrazioni).

### Verbi che oggi non controllano nulla

Quattro interruttori non hanno alcun endpoint dietro nell'API attuale: **lettura su LLM**, **scrittura su Cronologia Messaggi**, **scrittura su Eventi Webhook** e **scrittura su Registri di audit**. La console li mostra tutti e quattro concessi e bloccati, e non puoi spegnerli. Salvarne uno come "spento" sarebbe definitivo: il completamento dei permessi mancanti aggiunge solo ciò che manca a una concessione, quindi nulla lo riaccenderebbe se una release futura desse a quel verbo qualcosa da controllare.

Concederli non dà nulla, perché il lavoro avviene altrove. L'assistente IA dipende dalla scrittura su LLM. La cronologia dei messaggi è in sola lettura perché le sue righe le scrive la pipeline di invio. Le callback in entrata dei provider arrivano su route che non hanno sessione e non controllano alcun permesso. Il registro di audit lo scrive la piattaforma stessa, e la sua unica impostazione modificabile, la conservazione, è riservata al proprietario e non dipende da alcun permesso.

### La scrittura su Workspace è più ristretta di quanto sembri

L'unica impostazione del workspace che il permesso **Workspace** ti lascia cambiare sono le etichette dei campi personalizzati dei contatti. **Non** copre:

- Rinominare il workspace, cambiarne le impostazioni generali o eliminarlo: riservato al proprietario.
- Creare, aggiornare o eliminare un'integrazione: riservato al proprietario. La scrittura su Workspace non lo concede, e un proprietario può farlo anche senza.
- Le impostazioni del blog, che dipendono dalla scrittura su Blog.
- Le impostazioni di web analytics, che dipendono dalla scrittura su Web Analytics.

Chi riceve il blog o le statistiche del sito riceve quindi anche la configurazione di quella funzione a livello di workspace, compreso l'interruttore che la attiva o la disattiva.

## Azioni riservate al proprietario

Nessun permesso le concede. Restano al proprietario del workspace, qualunque cosa abbia un membro o una chiave:

- Rinominare il workspace, cambiarne le impostazioni generali ed eliminarlo
- Creare, aggiornare ed eliminare integrazioni, e gli endpoint di configurazione di Amazon SES
- Registrare webhook presso un provider email, perché usa le credenziali del provider salvate nella tua integrazione
- Provare un provider email, cosa che invia un'email di prova con le credenziali del provider salvate nella tua integrazione
- Rigenerare il segreto di firma di una subscription webhook e leggerlo (per tutti gli altri è oscurato)
- Invitare un membro, rimuovere un membro e impostare i permessi di un membro
- Creare un'API Key
- Trasferire la proprietà del workspace

## Permessi che vanno oltre il loro nome

Leggi questi punti prima di concederli a una chiave che non controlli del tutto.

- **La scrittura su Contatti elimina e sovrascrive in blocco.** Copre `/api/contacts.delete` e `/api/contacts.import`, che sovrascrive ogni campo presente in ciascuna riga: una sola chiamata può riscrivere l'intero database dei contatti. Anche la lettura su Contatti va oltre i profili: copre la timeline del contatto e gli eventi personalizzati.
- **La scrittura su Liste è una scrittura implicita su Contatti.** Iscrivere un indirizzo con `/api/lists.subscribe` crea o sovrascrive l'intero record di quel contatto con tutti i campi presenti nella richiesta, **senza bisogno della scrittura su Contatti**, quindi una chiave che ha solo la scrittura su Liste può riscrivere i dati dei contatti. La stessa chiamata può iscrivere qualcuno a una lista che non è pubblica. Concedi la scrittura su Liste solo dove concederesti la scrittura su Contatti.
- **La scrittura su Broadcast invia.** L'interruttore che permette di preparare una campagna permette anche di inviarla a tutto il pubblico, con `/api/broadcasts.schedule` oppure avviando o azzerando l'attività di invio sottostante.
- **La scrittura su Automazioni legge i contatti, modifica le liste e invia email.** Un nodo webhook invia il record completo del contatto a qualsiasi URL indicato dall'automazione, e nessuno controlla i permessi mentre un'automazione gira. Altri nodi aggiungono e rimuovono contatti dalle liste e inviano email. Questo interruttore raggiunge quindi i dati dei contatti, l'appartenenza alle liste e l'invio senza alcun permesso su Contatti, Liste o Transazionale.
- **La lettura su Automazioni espone dei segreti.** La configurazione dei nodi webhook che restituisce include i token bearer impostati su quei nodi.
- **La scrittura su Blog esegue JavaScript sul tuo dominio.** Comprende la pubblicazione di un tema, il cui `scripts.js` viene servito a ogni visitatore del dominio personalizzato del tuo blog. Permette anche di attivare e disattivare la funzione blog.
- **Template copre i blocchi riutilizzabili.** Chi ha la scrittura su Template può modificare, sostituire o eliminare i blocchi salvati del workspace. I template esistenti mantengono la propria copia, mentre gli inserimenti futuri ricevono il blocco aggiornato. I blocchi sono salvati con le impostazioni del workspace, quindi il loro contenuto torna anche nel record del workspace.
- **Web Analytics copre le annotazioni.** Le annotazioni non hanno un permesso proprio, quindi questo permesso consente anche di scrivere sulla timeline condivisa che tutti leggono. Il raccoglitore pubblico del tracciamento non dipende da alcun permesso: accetta dati senza autenticazione.
- **La scrittura su Subscription Webhook riceve dati di contatti ed email.** Una subscription sceglie gli eventi che trasporta, quindi chi ha questo permesso può iscriversi agli eventi di contatti ed email e farsi consegnare quei dati a qualsiasi URL. La lettura apre il log delle consegne, che contiene i payload stessi. Vedi [Webhook](https://www.notifuse.com/it/docs/features/webhooks.md).
- **La lettura su Segmenti più la lettura su Contatti sono uno strumento di interrogazione.** `/api/segments.preview` accetta qualsiasi definizione, non solo un segmento salvato, quindi la coppia permette di contare i contatti su qualsiasi condizione relativa ad attributi, appartenenza alle liste, eventi personalizzati e timeline, un conteggio alla volta. La sola lettura su Segmenti non lo permette.
- **La lettura su Cronologia Messaggi equivale a dati dei contatti.** Il log contiene gli indirizzi dei destinatari e i dati usati per comporre ogni messaggio.
- **La scrittura su LLM ha un costo.** Le richieste all'assistente IA vanno al provider IA che hai configurato, fatturate al tuo workspace, senza limite per chiave. Con un'integrazione Firecrawl configurata, permette anche all'assistente di estrarre contenuti e fare ricerche sul web con le tue credenziali.

### Invii transazionali e contatti

**La sola scrittura su Transazionale basta per inviare**, quindi una chiave dedicata solo all'invio è praticabile. Le regole sono le stesse via API e via [bridge SMTP](https://www.notifuse.com/it/docs/features/transactional-api.md):

- **Senza la scrittura su Contatti**, l'invio crea comunque il contatto destinatario se non esiste, ma salva solo l'indirizzo email e non modifica mai un contatto esistente.
- **Senza la lettura su Contatti**, un invio che imposta `cc` o `bcc` viene rifiutato, perché l'oggetto viene composto a partire dal record completo di ogni destinatario. Sul bridge SMTP, questi indirizzi vengono dagli header `Cc:` e `Bcc:` del messaggio.

La scrittura su Transazionale invia email reali da due endpoint, `/api/transactional.send` e `/api/transactional.testTemplate`, e dal bridge SMTP. Provare un provider email (`/api/email.testProvider`) è riservato al proprietario del workspace, come creare e modificare le integrazioni, qualunque siano i permessi della chiave. Un'email di prova (`/api/transactional.testTemplate`) richiede anche la lettura su Template, perché legge il template con i tuoi permessi, e la lettura su Liste quando viene inviata per una lista di distribuzione. Anche creare una notifica transazionale richiede la lettura su Template, e così pure modificarne una con i suoi `channels`, che la console invia quando modifichi una notifica non gestita da alcuna integrazione.
