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.

Achtung

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 & 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:

curl

curl https://api.accessful.de/api/v1/upload-service/job-status/<caseId> \
  -H "X-API-Key: ak_dein_key_hier"

Node.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:

   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-Body. Verlasse dich auf den Statuscode. Ein 403 kommt aus der Anwendung selbst und trägt einen Problem-Details-Body, wie andere Anwendungsfehler.