# Autenticazione

Come vengono autenticate le richieste: l’intestazione X-API-Key, da dove arrivano le chiavi e che cosa succede quando ne manca una o è sbagliata.

Ogni richiesta all’API di PDF Blocks viene autenticata con una chiave API segreta
inviata nell’intestazione `X-API-Key`, su HTTPS. Non ci sono token da scambiare
né sessioni da gestire: una sola intestazione su ogni chiamata.

## L’intestazione X-API-Key

Inviare la chiave nell’intestazione `X-API-Key`, esattamente con queste maiuscole
e minuscole. Il documento viaggia nel corpo `multipart/form-data` come di
consueto:

```bash title="cURL"
curl https://api.pdfblocks.com/v1/add_text_watermark \
  -H 'X-API-Key: your_api_key' \
  -F file=@input.pdf \
  -F line_1='CONFIDENTIAL' \
  -o watermarked.pdf
```

Una sola chiave funziona su tutte le regioni: cambia soltanto l’URL di base.
Vedere [Regioni e residenza dei dati](/docs/api/regions-and-data-residency) per
l’elenco completo degli endpoint.

## Ottenere una chiave API

Le chiavi si creano e si gestiscono dalla
[dashboard](https://dashboard.pdfblocks.com). Una chiave viene mostrata per
intero una sola volta, al momento della creazione: conviene copiarla in un posto
sicuro. Va trattata come una password: chiunque la possieda può inviare richieste
addebitate sull’account.

## Solo HTTPS

<Warning>
  L’API è servita esclusivamente su HTTPS. Le richieste a `http://` vengono
  rifiutate e la chiave non deve mai viaggiare su una connessione non
  crittografata. Chiamare sempre l’URL di base `https://`.
</Warning>

## Tenere le chiavi fuori dal controllo del codice sorgente

Non inserire mai una chiave direttamente nel codice né sottoporla a commit in un
repository. Leggerla invece da una variabile d’ambiente o da un gestore di
segreti in fase di esecuzione:

```bash title="cURL"
export PDFBLOCKS_API_KEY='your_api_key'

curl https://api.pdfblocks.com/v1/add_text_watermark \
  -H "X-API-Key: $PDFBLOCKS_API_KEY" \
  -F file=@input.pdf \
  -F line_1='CONFIDENTIAL' \
  -o watermarked.pdf
```

Ruotare le chiavi periodicamente e ogni volta che una di esse potrebbe essere
stata esposta. Creare la sostituta nella
[dashboard](https://dashboard.pdfblocks.com), distribuirla, poi eliminare la
vecchia chiave: dato che la chiave viene inviata a ogni richiesta, la rotazione è
solo una modifica di configurazione, senza codice da riscrivere. Emettere una
chiave distinta per ogni applicazione, così è possibile revocarne una senza
compromettere le altre.

## Quando l’autenticazione non riesce

Una chiave mancante, malformata o non valida restituisce un `401 Unauthorized`
con un corpo `application/problem+json`:

```json
{
  "type": "https://www.pdfblocks.com/docs/api/v1/error/401",
  "title": "The request is missing a valid API key.",
  "status": 401
}
```

Verificare che il nome dell’intestazione sia esattamente `X-API-Key`, che il
valore sia la chiave completa e che si stia chiamando un URL `https://`. Vedere
[Errori](/docs/api/errors) per tutti i codici di stato e la forma completa della
risposta.