Produkt- und API-Leitfaden

Authentifizierung

Wozu ein Schlüssel dient

Jeder Aufruf enthält einen Schlüssel. Dieser gehört zum Arbeitsbereich statt zu einer Person und funktioniert deshalb auch nach deren Ausscheiden weiter. Erstellen Sie ihn unter Konto, API-Schlüssel: Der geheime Wert wird einmal angezeigt, die Berechtigungsbereiche bestimmen die erlaubten Aktionen.

Jede Anfrage enthält einen API-Schlüssel. Erstellen Sie ihn auf der Seite „API-Schlüssel“ in Ihrem Konto; er wird nur bei der Erstellung einmal angezeigt und nie lesbar gespeichert.

X-PDFgine-Key: pdfgine_live_xxxxxxxxxxxxxxxxxxxxxxxx

Binden Sie den Schlüssel niemals in einen Browser oder eine mobile App ein. Führen Sie die Aufrufe auf Ihrem eigenen Server aus.

Jeder Schlüssel besitzt Berechtigungsbereiche. Ein Schlüssel, der nur Dokumente erstellt, kann daher keine Vorlagen ändern.

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

Ein erfolgreicher und ein fehlgeschlagener Aufruf

Der erste Aufruf listet Ihre Vorlagen auf. Der zweite sendet einen widerrufenen Schlüssel, und genau das teilt die Antwort mit.

cURL 
# Der Schlüssel gehört in die Umgebung, nicht in den Code
export PDFGINE_KEY="pdfgine_live_..."

curl -i https://api.pdfgine.com/api/v1/templates \
  -H "X-PDFgine-Key: $PDFGINE_KEY"
Antwort 
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"
}

Jeder Fehlerinhalt enthält eine correlationId. Nennen Sie diese beim Kontakt mit dem Support, damit die Anfrage ohne Rätselraten in den Protokollen gefunden wird.

Häufige Fehler

  • Der Schlüssel gehört in den Header X-PDFgine-Key. Ein Authorization: Bearer-Token wird nicht gelesen; deshalb antwortet der Aufruf mit 401, selbst wenn der Schlüssel gültig ist.
  • 401 und 403 bedeuten Unterschiedliches. 401 heißt „Ich weiß nicht, wer Sie sind“; 403 heißt „Ich kenne Sie, aber dieser Schlüssel hat diesen Berechtigungsbereich nicht“. Ein Schlüssel ohne templates:write kann keine Vorlage speichern. Berechtigungsbereiche werden bei der Erstellung festgelegt.
  • Der geheime Wert wird nur einmal angezeigt. Geht er verloren, kann er nicht erneut gelesen werden. Widerrufen Sie den Schlüssel und erstellen Sie einen neuen.
  • Ein Schlüssel gehört niemals in einen Browser oder eine mobile App. Alles, was an ein Gerät ausgeliefert wird, kann ausgelesen werden. Rufen Sie PDFgine von Ihrem eigenen Server aus auf.
  • Ein Widerruf wirkt ab dem nächsten Aufruf. Stellen Sie zuerst den neuen Schlüssel bereit und widerrufen Sie dann den alten, sonst schlagen laufende Aufrufe fehl.