# Autenticazione

Ogni richiesta API deve contenere la tua chiave API in modo che <span data-t="appName">Your AI Connector</span> sappia chi sei e su quale account operare. Puoi inviare la chiave in quattro modi diversi: tutti funzionano su ogni endpoint che accetta l'autenticazione tramite chiave API, quindi scegli quello più adatto alla tua configurazione.

L'accesso all'API è una funzionalità a pagamento. Se il tuo piano non la include, le richieste verranno rifiutate con un `403` anche se la chiave stessa è valida — vedi [Il blocco delle funzionalità a pagamento](#the-paid-feature-gate) qui sotto. Per generare una chiave, vedi [Accesso API](../integrations/api-access.md).

> **Solo HTTPS.** Tutte le richieste devono utilizzare una connessione sicura. Le richieste HTTP in chiaro vengono rifiutate prima ancora che venga eseguita l'autenticazione.

---

## Panoramica dei quattro metodi

| Metodo | Vettore | Quando usarlo |
|---|---|---|
| Parametro di query | `?apiKey=YOUR_API_KEY` | Test rapidi e URL del browser |
| Header | `X-API-Key: YOUR_API_KEY` | Integrazioni in produzione |
| Header Bearer | `Authorization: Bearer YOUR_API_KEY` | Integrazioni in produzione |
| Token ID Firebase | `Authorization: Bearer <ID token>` | Solo sessioni di app di prima parte |

Quando ne è presente più di uno, il parametro di query ha la precedenza, seguito dall'header `X-API-Key` e infine dal token bearer. In pratica, se ne invia sempre solo uno.

---

## 1. Parametro di query — `?apiKey=`

Aggiungi la tua chiave alla fine dell'indirizzo web. Questa è la forma più semplice e funziona sempre, il che la rende ideale per test rapidi, script e qualsiasi strumento meno recente.

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/contacts?apiKey=YOUR_API_KEY"
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/contacts?apiKey=YOUR_API_KEY");
const data = await res.json();
```

**Python**

```python
import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/contacts",
    params={"apiKey": "YOUR_API_KEY"},
)
data = res.json()
```

> **Attenzione:** Gli indirizzi web finiscono nella cronologia del browser, nei log di accesso del server e nei log dei proxy. Per qualsiasi cosa che vada oltre un test rapido, preferisci uno dei metodi tramite header qui sotto, in modo che la tua chiave non venga scritta su disco in chiaro.

---

## 2. Header `X-API-Key`

Invia la chiave in un header dedicato. Questo la mantiene fuori dall'URL ed è la scelta consigliata per la produzione.

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/contacts" \
  -H "X-API-Key: YOUR_API_KEY"
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/contacts", {
  headers: {
    "X-API-Key": "YOUR_API_KEY",
  },
});
const data = await res.json();
```

**Python**

```python
import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/contacts",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
```

---

## 3. Intestazione `Authorization: Bearer`

È inoltre possibile passare la chiave come bearer token standard. Questo è utile quando il proprio client HTTP o framework dispone già di un supporto integrato per le intestazioni `Authorization`.

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/contacts" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/contacts", {
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
  },
});
const data = await res.json();
```

**Python**

```python
import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/contacts",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)
data = res.json()
```

L'API distingue automaticamente la chiave API dal token di accesso, quindi questo metodo funziona esattamente come `X-API-Key`.

---

## 4. Token ID Firebase (solo per applicazioni first-party)

Se stai creando un'applicazione first-party che autentica gli utenti tramite il login di <span data-t="appName">Your AI Connector</span>, puoi passare il token ID Firebase dell'utente autenticato come bearer token invece di una chiave API:

```
Authorization: Bearer <Firebase ID token>
```

Il token viene verificato a ogni richiesta e associato all'account autenticato. **Questo metodo è destinato esclusivamente alle sessioni di applicazioni first-party**: non è possibile generare questi token da un'integrazione esterna e non esiste alcun modo per ottenerne uno senza passare attraverso la normale procedura di login dell'applicazione. Per le integrazioni server-to-server e di terze parti, utilizza una chiave API (metodi 1–3).

---

## Quando utilizzare ciascun metodo

- **Test rapidi e script una tantum** → parametro di query (`?apiKey=`). Il più veloce da digitare, funziona nel browser.
- **Integrazioni in produzione e chiamate server-to-server** → `X-API-Key` o `Authorization: Bearer YOUR_API_KEY`. Mantiene la chiave al di fuori di URL e log.
- **Applicazioni first-party con un utente <span data-t="appName">Your AI Connector</span> autenticato** → `Authorization: Bearer <Firebase ID token>`.

---

## Ambiti delle chiavi

Il tuo account ha una **chiave API principale**: quella che trovi in **Impostazioni → Integrazioni → Chiave API**. Ha accesso completo a tutto ciò che l'account può fare.

Puoi anche creare **chiavi con ambito limitato**: chiavi denominate che accedono solo alle parti dell'API che scegli, ad esempio una chiave di sola lettura limitata ad Analytics per una dashboard di reportistica. Una chiave con ambito limitato viene inviata esattamente come la chiave principale (uno dei metodi 1–3 sopra), ma viene verificata rispetto alle proprie autorizzazioni a ogni richiesta:

- **Al di fuori delle aree consentite viene rifiutata.** Una scrittura con una chiave di sola lettura, o una chiamata a una sezione per la quale la chiave non è stata autorizzata, restituisce `403` — `key_read_only` o `key_scope_denied` nel campo `error_code`. Il controllo è deliberatamente rigoroso: tutto ciò che non è chiaramente all'interno delle aree consentite della chiave viene rifiutato invece di essere consentito, quindi se vedi uno di questi `403`, la chiave semplicemente non copre quell'endpoint.
- **Ha il proprio budget di limitazione della frequenza (rate-limit).** Una chiave con ambito limitato viene conteggiata separatamente dalla tua chiave principale, quindi una dashboard molto attiva che utilizza una chiave con ambito limitato non può esaurire il budget da cui dipendono le tue altre integrazioni. Scegli quel budget al minuto quando crei la chiave.
- **Non può gestire le chiavi API.** Solo il proprietario dell'account — effettuando l'accesso o utilizzando la chiave principale — può elencare, creare, modificare, ruotare o revocare le chiavi. Una chiave con ambito limitato non può mai creare una chiave con privilegi più ampi.

Vedi [Chiavi API](api-keys.md) per sapere come creare, modificare e revocare chiavi con ambito limitato.

---

## Il blocco delle funzionalità a pagamento

L'accesso all'API è una funzionalità a pagamento. Quando il tuo piano non la include, una richiesta con una chiave altrimenti valida viene rifiutata con `403`:

```json
{
  "success": false,
  "error_code": 403,
  "error": "This action requires the \"api_access\" feature, which is not enabled for this account."
}
```

If you see this, check your plan or contact [<span data-t="supportEmail">hi@youraiconnector.com</span>](mailto:hi@youraiconnector.com). A missing or wrong key returns `401` instead:

```json
{
  "success": false,
  "error_code": 401,
  "error": "Invalid API key"
}
```

---

## Protezione della chiave

- **Tratta la chiave come una password.** La tua chiave principale garantisce l'accesso completo al tuo account. Se devi fornire una chiave a uno strumento o a una persona che ne ha bisogno solo in parte, crea invece una chiave con ambito limitato — vedi [Ambiti delle chiavi](#key-scopes).
- **Mantienila lato server.** Non incorporarla mai in JavaScript del browser, in un pacchetto di app mobile o in qualsiasi codice che un utente finale possa leggere.
- **Archiviala in un gestore di segreti** o nella configurazione lato server, non nel controllo del codice sorgente.
- **Ruotala se viene compromessa.** Genera una nuova chiave dalla dashboard o chiama `POST https://api.youraiconnector.com/v1/api-keys/rotate` — questo invalida immediatamente quella vecchia. Vedi [Chiavi API](api-keys.md).
- **Usa sempre HTTPS** in modo che la chiave sia crittografata durante il transito.

---

## Passaggi successivi

- [Guida introduttiva](getting-started.md) — la tua prima richiesta e le guide alle risorse.
- [Errori e paginazione](errors-and-pagination.md) — gestisci gli errori e scorri i risultati.
- [Chiavi API](api-keys.md) — ruota, revoca e controlla l'utilizzo della tua chiave.