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