# Autenticazione

> Autentica le richieste API con una chiave API o un token di accesso OAuth di tipo Bearer, scegli il permesso full o sending, limita le chiavi a un dominio e gestisci gli errori di autenticazione.

Ogni richiesta all’API di Emailit deve contenere una credenziale nell’header `Authorization`. Questa pagina descrive i due tipi di credenziali (chiavi API e token di accesso OAuth), cosa consente ciascun permesso (scope) e tutti gli errori di autenticazione che puoi ricevere.

## Chiavi API

Una chiave API appartiene a un solo workspace, e ogni richiesta fatta con quella chiave agisce su quel workspace. Le chiavi hanno questo aspetto:

```text
secret_Xq7pL2mN9vB4kR8tW1yZ6cH3jF5dS0aG
```

Cioè `secret_` seguito da 32 lettere e cifre. Le chiavi create prima del formato `secret_` non hanno prefisso e continuano a funzionare.

Crea le chiavi nel pannello in **Email API → API Keys**, oppure con [Crea una chiave API](/it/docs/api-reference/api-keys/create/). Il secret viene mostrato una sola volta, quando crei o [rigeneri](/it/docs/api-reference/api-keys/regenerate/) la chiave, quindi salvalo subito. Per gestirle, vedi [Chiavi API](/it/docs/developers/api-keys/).

Le stesse chiavi funzionano come password SMTP per l’[SMTP relay](/it/docs/smtp/settings/).

## Invia la chiave con ogni richiesta

Usa lo schema `Bearer` nell’header `Authorization`. L’API non accetta chiavi nella query string né nel corpo della richiesta.

**cURL**

```bash
curl https://api.emailit.com/v2/domains \
  -H "Authorization: Bearer $EMAILIT_API_KEY"
```

**Node.js**

```javascript
const response = await fetch('https://api.emailit.com/v2/domains', {
  headers: { Authorization: `Bearer ${process.env.EMAILIT_API_KEY}` },
});
const domains = await response.json();
```

**Python**

```python
import os
import requests

response = requests.get(
    "https://api.emailit.com/v2/domains",
    headers={"Authorization": f"Bearer {os.environ['EMAILIT_API_KEY']}"},
)
domains = response.json()
```

Gli SDK impostano questo header per te quando passi la chiave al client.

## Permessi

Ogni chiave ha uno dei due permessi. Lo scegli quando crei la chiave e non puoi cambiarlo in seguito.

| Permesso | Può chiamare | Usalo per |
| --- | --- | --- |
| `full` | Tutti gli endpoint dell’API. È il valore predefinito. | Strumenti di back office, script e integrazioni che gestiscono domini, contatti, template o webhook. |
| `sending` | Solo gli endpoint di invio elencati sotto. | Server applicativi che si limitano a inviare email. |

Una chiave `sending` può chiamare questi endpoint e nient’altro:

| Endpoint | Descrizione |
| --- | --- |
| `POST /emails` | [Invia un’email](/it/docs/api-reference/emails/send/) |
| `POST /emails/{id}` | [Aggiorna un’email programmata](/it/docs/api-reference/emails/update/) |
| `POST /emails/{id}/cancel` | [Annulla un’email](/it/docs/api-reference/emails/cancel/) |
| `POST /emails/{id}/retry` | [Ritenta un’email](/it/docs/api-reference/emails/retry/) |
| `POST /emails/{id}/forward` | [Inoltra un’email](/it/docs/api-reference/emails/forward/) |

Per leggere le email (elenco, recupero, MIME grezzo, corpo, metadati, allegati e stato) serve una chiave `full`. Quando una chiave `sending` chiama qualsiasi altro endpoint, l’API restituisce `403` con `Permission denied: full` (o `Permission denied: read` per gli endpoint di lettura delle email).

[Tutti gli endpoint](/it/docs/api-reference/endpoints/) indica il permesso di ogni endpoint.

## Limita una chiave a un dominio

Una chiave `sending` può anche essere vincolata a un solo dominio di invio. Passa l’ID del dominio come `sending_domain_id` quando [crei la chiave](/it/docs/api-reference/api-keys/create/). Una chiave limitata può inviare solo da indirizzi di quel dominio. Qualsiasi altro dominio in `from` restituisce `403`:

```json
{
  "error": "Domain not authorized",
  "message": "API key is not authorized to send from this domain"
}
```

Le limitazioni per dominio valgono solo per le chiavi `sending`. Una chiave `full` ha sempre accesso a tutti i domini del workspace.

## Token di accesso OAuth

Le app che agiscono per conto di un utente di Emailit, come i client MCP e le integrazioni di terze parti, non chiedono una chiave API. Usano invece OAuth 2.1: l’utente accede a Emailit, sceglie i workspace che l’app può usare (tutti o solo alcuni) e approva il permesso `sending` o `full`, e l’app riceve un token di accesso. L’utente può modificare o revocare questo accesso in [App collegate](/it/docs/account/connected-apps/).

Invia i token di accesso nello stesso header delle chiavi API:

```http
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…
```

Un token di accesso è valido per 15 minuti e agisce sul workspace predefinito dell’autorizzazione, con il permesso concesso e il ruolo che l’utente ha in quel workspace. Le app lo rinnovano con il token di aggiornamento (refresh token). Per crearne una, vedi [App OAuth](/it/docs/developers/oauth-apps/).

## Errori di autenticazione

L’autenticazione viene eseguita prima di qualsiasi altra cosa, quindi questi errori possono arrivare da qualsiasi endpoint.

| Stato | `message` o `error` | Causa | Soluzione |
| --- | --- | --- | --- |
| `401` | `API key required` | L’header `Authorization` manca o non inizia con `Bearer `. | Invia `Authorization: Bearer <key>`. |
| `401` | `Valid API key required` | L’header ha il prefisso `Bearer` ma nessun token. | Controlla che la variabile che contiene la chiave non sia vuota. |
| `401` | `Invalid API key` | La chiave non esiste, è stata eliminata o è stata rigenerata (il vecchio secret smette di funzionare), oppure un token OAuth è scaduto. | Usa una chiave valida, oppure rinnova il token OAuth. |
| `403` | `Workspace is suspended` | Il workspace è sospeso. | Contatta il [supporto](/contact/). |
| `403` | `Permission denied: full` | Una chiave `sending` ha chiamato un endpoint che richiede `full`. | Usa una chiave `full`. |
| `403` | `Domain not authorized` | Una chiave limitata a un dominio ha inviato da un altro dominio. | Invia dal dominio della chiave o usa un’altra chiave. |
| `403` | `unverified_workspace_recipient` | Il workspace non è ancora verificato e un destinatario non è un membro del workspace. | Vedi [Workspace non verificati](#unverified-workspaces). |
| `503` | `Authentication service unavailable` | Un problema temporaneo da parte nostra. | Ritenta con backoff. |

**401**

```json
{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Invalid API key"
}
```

**403 Permesso**

```json
{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "Permission denied: full"
}
```

**403 Sospeso**

```json
{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "Workspace is suspended"
}
```

**403 Non verificato**

```json
{
  "code": "unverified_workspace_recipient",
  "error": "Workspace not verified",
  "message": "Unverified workspaces can only send to workspace members' account emails. Blocked recipient: ada@example.com.",
  "blocked_recipients": ["ada@example.com"]
}
```

## Workspace non verificati

I nuovi workspace partono non verificati. Finché Emailit non approva l’[accesso alla produzione](/it/docs/workspaces/production-access/), l’API invia solo agli indirizzi email degli account dei membri del workspace. Un invio, un nuovo tentativo o un inoltro verso chiunque altro restituisce `403` con il codice `unverified_workspace_recipient` e l’elenco `blocked_recipients`, e le campagne non possono essere inviate affatto. Le chiavi API funzionano normalmente per tutto il resto.

## Mantieni segrete le chiavi

Una chiave API dà accesso al workspace, quindi trattala come una password.

- Chiama l’API solo dal tuo server. Non inserire mai una chiave nel JavaScript del browser, in un’app mobile o in altro codice che gira sul dispositivo di qualcun altro.
- Tieni le chiavi fuori dal controllo di versione. Caricale da variabili d’ambiente o da un gestore di secret.
- Crea una chiave per ogni applicazione e ambiente, e dalle il nome del posto in cui la usi, così puoi revocarne una senza bloccare le altre.
- Dai a ogni chiave solo l’accesso che le serve: una chiave `sending`, limitata a un dominio, basta per la maggior parte delle applicazioni.
- Controlla `last_used_at` in [Elenca le chiavi API](/it/docs/api-reference/api-keys/list/) ed elimina le chiavi che non usi più.
- Se una chiave viene esposta, [rigenerala](/it/docs/api-reference/api-keys/regenerate/) o [eliminala](/it/docs/api-reference/api-keys/delete/) subito. Il vecchio secret smette di funzionare immediatamente.

## Vedi anche

  - [Chiavi API](/it/docs/developers/api-keys/): Crea, limita e ruota le chiavi nel pannello.
  - [Errori](/it/docs/api-reference/errors/): Tutti i formati di errore e i codici di stato.
  - [App OAuth](/it/docs/developers/oauth-apps/): Permetti agli utenti di collegare la tua app al loro workspace.
  - [Accesso alla produzione](/it/docs/workspaces/production-access/): Fai verificare il workspace per inviare a chiunque.

---
Fonte: https://emailit.com/it/docs/api-reference/authentication/