Guide du produit et de l’API

Authentification

À quoi sert une clé

Chaque appel comporte une clé appartenant à l’espace de travail plutôt qu’à une personne ; elle continue donc à fonctionner lorsqu’un membre part. Créez-la dans Compte, Clés API : le secret est affiché une fois et ses droits sont fixés par ses périmètres.

Chaque requête comporte une clé API. Créez-la depuis l’écran des clés API de votre compte ; elle est affichée une seule fois à sa création et n’est jamais stockée sous une forme lisible.

X-PDFgine-Key: pdfgine_live_xxxxxxxxxxxxxxxxxxxxxxxx

N’intégrez jamais la clé dans un navigateur ou une application mobile. Effectuez les appels depuis votre propre serveur.

Chaque clé possède un ensemble de périmètres ; une clé qui génère uniquement des documents ne peut pas modifier les modèles.

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

Un appel qui fonctionne et un autre qui échoue

Le premier appel liste vos modèles. Le second envoie une clé révoquée, et la réponse l’indique précisément.

cURL

# La clé se trouve dans l’environnement, pas dans le code
export PDFGINE_KEY="pdfgine_live_..."

curl -i https://api.pdfgine.com/api/v1/templates \
  -H "X-PDFgine-Key: $PDFGINE_KEY"

Réponse

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"
}

Chaque corps d’erreur contient un correlationId. Communiquez-le à l’assistance pour retrouver la requête dans les journaux sans recherche au hasard.

Les problèmes les plus courants

La clé se place dans l’en-tête X-PDFgine-Key. Un jeton Authorization: Bearer n’est pas lu ; l’appel répond donc 401 même si la clé est valide.
401 et 403 n’ont pas le même sens. 401 signifie « je ne sais pas qui vous êtes » ; 403 signifie « je vous connais, mais cette clé ne possède pas ce périmètre ». Une clé sans templates:write ne peut pas enregistrer un modèle. Les périmètres sont fixés à la création de la clé.
Le secret n’est affiché qu’une fois. S’il est perdu, il n’est pas possible de le relire ; révoquez cette clé et créez-en une autre.
Une clé n’a jamais sa place dans un navigateur ou une application mobile. Tout ce qui est envoyé à un appareil peut y être lu ; appelez PDFgine depuis votre propre serveur.
La révocation prend effet dès l’appel suivant. Déployez d’abord la nouvelle clé, puis révoquez l’ancienne ; sinon les appels en cours échoueront.