# Authentifizierung Wie Anfragen authentifiziert werden: der Header X-API-Key, woher die Schlüssel kommen und was geschieht, wenn einer fehlt oder falsch ist. Jede Anfrage an die API von PDF Blocks wird mit einem geheimen API-Schlüssel authentifiziert, der im Header `X-API-Key` über HTTPS gesendet wird. Es gibt keine Token auszutauschen und keine Sitzungen zu verwalten: ein Header bei jedem Aufruf. ## Der Header X-API-Key Senden Sie Ihren Schlüssel im Header `X-API-Key` (genau in dieser Schreibweise). Das Dokument geht wie gewohnt in den Anfragetext vom Typ `multipart/form-data`: ```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 ``` Ein Schlüssel funktioniert in jeder Region: Nur die Basis-URL ändert sich. Siehe [Regionen und Datenresidenz](/docs/api/regions-and-data-residency) für die vollständige Liste der Endpoints. ## Einen API-Schlüssel erhalten Schlüssel erstellen und verwalten Sie im [Dashboard](https://dashboard.pdfblocks.com). Ein Schlüssel wird nur einmal vollständig angezeigt, nämlich bei seiner Erstellung: Kopieren Sie ihn an einen sicheren Ort. Behandeln Sie ihn wie ein Passwort, denn wer ihn besitzt, kann Anfragen stellen, die Ihrem Konto in Rechnung gestellt werden. ## Nur HTTPS <Warning> Die API wird ausschließlich über HTTPS bereitgestellt. Anfragen an `http://` werden abgewiesen, und Ihr Schlüssel darf niemals über eine unverschlüsselte Verbindung übertragen werden. Rufen Sie immer die Basis-URL mit `https://` auf. </Warning> ## Schlüssel aus der Versionsverwaltung heraushalten Schreiben Sie einen Schlüssel niemals fest in den Code und übernehmen Sie ihn niemals in ein Repository. Lesen Sie ihn stattdessen zur Laufzeit aus einer Umgebungsvariablen oder einem Secret Manager: ```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 ``` Wechseln Sie Schlüssel regelmäßig und immer dann, wenn einer offengelegt worden sein könnte. Erstellen Sie den Ersatz im [Dashboard](https://dashboard.pdfblocks.com), bringen Sie ihn in Betrieb und löschen Sie dann den alten Schlüssel: Da ein Schlüssel bei jeder Anfrage mitgesendet wird, ist ein Wechsel nur eine Änderung der Konfiguration, ohne Code neu zu schreiben. Geben Sie pro Anwendung einen eigenen Schlüssel aus, damit Sie einen widerrufen können, ohne die anderen zu stören. ## Wenn die Authentifizierung fehlschlägt Ein fehlender, fehlerhaft aufgebauter oder ungültiger Schlüssel gibt `401 Unauthorized` als Antworttext vom Typ `application/problem+json` zurück: ```json { "type": "https://www.pdfblocks.com/docs/api/v1/error/401", "title": "The request is missing a valid API key.", "status": 401 } ``` Prüfen Sie, ob der Name des Headers genau `X-API-Key` lautet, ob der Wert der vollständige Schlüssel ist und ob Sie eine URL mit `https://` aufrufen. Siehe [Fehler](/docs/api/errors) für alle Statuscodes und die vollständige Form der Antwort.