Guida al prodotto e alle API

Autenticazione

A cosa serve una chiave

Ogni chiamata contiene una chiave, che appartiene allo spazio di lavoro anziché a una persona e continua quindi a funzionare quando qualcuno se ne va. La crei in Account, Chiavi API: il segreto viene mostrato una volta e le azioni consentite sono definite dagli ambiti.

Ogni richiesta contiene una chiave API. La crei nella schermata delle chiavi API del tuo account; viene mostrata una sola volta alla creazione e non viene mai memorizzata in forma leggibile.

X-PDFgine-Key: pdfgine_live_xxxxxxxxxxxxxxxxxxxxxxxx

Non incorporare mai la chiave in un browser o in un'app mobile. Effettua le chiamate dal tuo server.

Ogni chiave ha un insieme di ambiti, quindi una chiave che genera solo documenti non può modificare i modelli.

templates:read   templates:write   documents:render
previews:manage  assets:read       assets:write
usage:read       api-keys:manage

Una chiamata riuscita e una non riuscita

La prima chiamata elenca i tuoi modelli. La seconda invia una chiave revocata e la risposta lo indica esattamente.

cURL 
# La chiave va nell'ambiente, non nel codice
export PDFGINE_KEY="pdfgine_live_..."

curl -i https://api.pdfgine.com/api/v1/templates \
  -H "X-PDFgine-Key: $PDFGINE_KEY"
Risposta 
HTTP/1.1 401 Unauthorized
Content-Type: application/problem+json

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.2",
  "title": "Unauthorized request",
  "status": 401,
  "detail": "The API key is invalid.",
  "correlationId": "0123b82d0a59e8b196a783af0e0e86bc"
}

Ogni corpo di errore contiene correlationId. Indicalo quando scrivi all'assistenza per trovare la richiesta nei log senza tentativi.

Gli errori più comuni

  • La chiave va nell'intestazione X-PDFgine-Key. Un token Authorization: Bearer non viene letto, quindi la chiamata risponde 401 anche se la chiave è valida.
  • 401 e 403 hanno significati diversi. 401 significa "non so chi sei"; 403 significa "ti conosco, ma questa chiave non ha tale ambito": una chiave senza templates:write non può salvare un modello. Gli ambiti vengono fissati alla creazione.
  • Il segreto viene mostrato una volta sola. Se lo perdi non puoi rileggerlo: revoca la chiave e creane un'altra.
  • Una chiave non deve mai trovarsi in un browser o in un'app mobile. Tutto ciò che viene distribuito a un dispositivo può essere letto: chiama PDFgine dal tuo server.
  • La revoca ha effetto dalla chiamata successiva. Distribuisci prima la nuova chiave, poi revoca la vecchia, altrimenti le chiamate in corso falliscono.