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

# Autenticazione e scope

> Assegna a ogni integrazione solo gli accessi necessari.

Le richieste REST, CLI e MCP locale usano una chiave API Emailx con scadenza. Titolari e admin del workspace creano le chiavi in Emailx, da **Impostazioni > Chiavi API**.

```http theme={null}
Authorization: Bearer <EMAILX_API_KEY>
```

Usa una chiave `ex_test_` per staging e una `ex_live_` solo sulla relativa installazione di produzione abilitata. Credenziali del provider e cookie browser non sono chiavi API.

## Scope disponibili

| Scope | Accesso |
| - | - |
| `workspaces:read` | Identità e ricerca dei workspace |
| `agency:read` | Accesso ai clienti, insieme allo scope della risorsa |
| `contacts:read` | Profili e ricerca per email |
| `contacts:write` | Creazione, modifica ed esclusione dai contatti email |
| `campaigns:read` | Campagne, sequenze e prospect |
| `campaigns:configure` | Configurare bozze inattive con revisione aggiornata; senza generazione o avvio |
| `campaigns:write` | Bozze, aggiunta prospect e pausa |
| `inbox:read` | Conversazioni salvate con risposte |
| `senders:read` | Metadati salvati dei mittenti |
| `team:read` | Membri attivi e responsabili delle notifiche; serve una nuova autorizzazione |
| `analytics:read` | Totali storici ed esiti registrati |

Gli scope limitano le azioni; i workspace autorizzati limitano i dati. Il ruolo corrente può restringere entrambi: un viewer non può scrivere e un'assegnazione di agenzia revocata perde accesso anche se la chiave contiene ancora il cliente. I workspace archiviati o in eliminazione non sono accessibili.

## Creare una chiave

1. In Emailx apri il menu del profilo e scegli **Chiavi API**. Titolari e admin vedono **Nuova chiave API**; membri e visualizzatori non possono creare chiavi.
2. Dai alla chiave un nome che dica dove viene usata, per esempio "sincronizzazione CRM".
3. Scegli i workspace che può usare. Titolari e admin di un’agenzia possono scegliere anche i workspace dei clienti.
4. Scegli i permessi. Parti da **Solo lettura** e aggiungi solo ciò che serve all’integrazione.
5. Scegli quando scade: 30, 90 o 180 giorni, oppure un anno.
6. Copia la chiave dalla schermata successiva. Emailx la mostra una sola volta e ne conserva solo un’impronta.

Una chiave non può mai fare più di chi l’ha creata. Se quella persona perde l’accesso a un workspace o lascia il team, le sue chiavi smettono subito di funzionare lì.

## Ruotare o revocare

Per ruotare una chiave creane una nuova, aggiorna il tuo archivio di segreti, verifica che `/me` funzioni con la nuova chiave e poi revoca quella vecchia. Per revocarla apri **Impostazioni > Chiavi API**, usa il menu della riga e scegli **Revoca**. Una chiave revocata smette subito di funzionare, anche per le attività in background non ancora avviate.

## Proteggere le credenziali

Esegui le richieste REST dal backend: l'API non concede accesso browser cross-origin. Non inserire chiavi nel codice della pagina, negli URL o negli strumenti di analytics. Per CLI/MCP usa un [file privato](https://docs.emailx.ai/it/cli/authentication.md). Per l'assistenza condividi `X-Request-Id`, non gli header di autorizzazione.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.