# Authentifizierung

Jede Anfrage wird mit einem einzigen **API-Key** authentifiziert. Du sendest ihn als
`X-API-Key`-Header — kein OAuth-Tanz, kein Token-Tausch.
**Geltungsbereich eines API-Keys:** Ein API-Key gibt ausschließlich Zugriff auf den **PDF-Upload-Service** — die Endpunkte
unter `/api/v1/upload-service/*` (Upload, Job-Status, Download, Löschen). Das ist die gesamte
öffentliche Verarbeitungs-Oberfläche.

## API-Key erstellen

Der normale Weg zu einem Key ist das **Accessful-Portal**: anmelden, **API-Keys** öffnen
und einen erstellen. Der Key wird bei der Erstellung **einmalig** angezeigt — kopiere ihn
sofort. Wir speichern nur einen Hash und können ihn danach nie wieder anzeigen.

Ein Key sieht so aus:

```
ak_oCe4cm015zL8vCbBne_wUZDcM6G1RWqD7Ekc2944EAA
```

- Präfix `ak_` gefolgt von 43 URL-sicheren Zeichen.
- Pro Konto sind bis zu **10 aktive Keys** möglich.
- Ein Key kann optional ein **Ablaufdatum** tragen; im Portal jederzeit widerrufbar.
**Caution:** Behandle den Key wie ein Passwort. Er ist an dein Konto gebunden und kann Cases hochladen,
herunterladen und **endgültig löschen**. Bette ihn niemals in Client-Code ein, den du an
Endnutzer auslieferst.

### Keys programmatisch verwalten (optional)

Wenn du Key-Rotation automatisierst: Die Verwaltungs-Endpunkte liegen unter
`/api/v1/auth/api-keys` und erfordern ein **OAuth2-Bearer-Token** aus deinem Portal-Login
(`Authorization: Bearer <jwt>`) — keinen API-Key:

| Methode &amp; Pfad | Zweck |
| --- | --- |
| `POST /api/v1/auth/api-keys` | Key erstellen — Antwort enthält den Klartext **einmalig** |
| `GET /api/v1/auth/api-keys` | Eigene Keys auflisten (Werte maskiert) |
| `POST /api/v1/auth/api-keys/{id}/revoke` | Key widerrufen |
| `DELETE /api/v1/auth/api-keys/{id}` | Key löschen |

## Key bei Anfragen senden

Füge jeder Anfrage den `X-API-Key`-Header hinzu:

```bash
curl https://api.accessful.de/api/v1/upload-service/job-status/<caseId> \
  -H "X-API-Key: ak_dein_key_hier"
```
```js
await fetch(`https://api.accessful.de/api/v1/upload-service/job-status/${caseId}`, {
  headers: { 'X-API-Key': process.env.ACCESSFUL_API_KEY },
});
```
```java
HttpRequest.newBuilder()
    .uri(URI.create("https://api.accessful.de/api/v1/upload-service/job-status/" + caseId))
    .header("X-API-Key", System.getenv("ACCESSFUL_API_KEY"))
    .GET().build();
```
## Key überprüfen

Teste einen Key, indem du einen zufälligen, nicht existierenden Case abfragst. Ein
funktionierender Key liefert **404** (der Case existiert nicht) — *nicht* 401.

1. Sende eine Status-Anfrage mit einer Wegwerf-Case-ID:

   ```bash
   curl -i https://api.accessful.de/api/v1/upload-service/job-status/00000000-0000-0000-0000-000000000000 \
     -H "X-API-Key: ak_dein_key_hier"
   ```

2. Lies die Statuszeile:

   - **`404 Not Found`** → dein Key wird akzeptiert. ✅
   - **`401 Unauthorized`** → der Key fehlt, ist ungültig oder widerrufen.

## Authentifizierungs-Fehler

| Status | Bedeutung |
| --- | --- |
| `401 Unauthorized` | Kein Key, ungültiger Key oder ein widerrufener/abgelaufener Key. |
| `403 Forbidden` | Der Key ist gültig, hat für diese Aktion aber keine Berechtigung. |

Ein fehlender oder ungültiger Key (**401**) wird am **Gateway** abgewiesen, bevor die Anfrage die
Anwendung erreicht — ein 401 trägt daher nie einen [Problem-Details](https://docs.accessful.de/de/errors/)-Body. Verlasse
dich auf den Statuscode. Ein **403** kommt aus der Anwendung selbst und trägt einen
Problem-Details-Body, wie andere Anwendungsfehler.