# 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.