Authentifizierung¶

Die REST-API akzeptiert zwei Auth-Mechanismen parallel:

Cookie-Session — wenn das Admin-UI selbst gegen die API arbeitet (Browser-basiert, CSRF-geschützt). Der Browser liefert das Session-Cookie automatisch mit.
X-API-Key-Header — für externe Integrationen (CI/CD, SIEM, Monitoring, Custom-Apps). API-Keys werden im UI unter Settings → API-Keys generiert.

API-Key-Format¶

nmg_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

nmg_ + 64 Hex-Zeichen. In der DB liegt nur der SHA-256-Hash plus die ersten 20 Zeichen für UI-Anzeige. Der volle Key wird einmalig bei der Erstellung zurückgegeben.

Beispiel-Request¶

curl -H 'X-API-Key: nmg_<...64hex...>' \
     https://mailguard.example.com:3443/api/v1/auth/me

Antwort:

{
  "data": {
    "actor_type": "api_token",
    "actor_id": "12345",
    "scope": "read-only",
    "rate_limit_per_minute": 100
  },
  "error": null,
  "message": "OK"
}

Response-Envelope¶

Jede Response — Erfolg wie Fehler — folgt der gleichen Form:

{
  "data": <payload> | null,
  "error": null | "<error-code-or-text>",
  "message": "<human-readable-status>"
}

data — endpoint-spezifischer Payload, null bei Fehler
error — null bei Erfolg, sonst Error-Code oder Raw-String
message — kurze Status-Beschreibung

Pattern für Client-Code: if (response.error === null) { ... }.

Fehler-Response¶

{
  "data": null,
  "error": "license_tier_insufficient",
  "message": "Standard-Lizenz benötigt für diese Operation"
}

HTTP-Status entspricht dem Charakter: - 401 Unauthorized — Auth fehlt oder Key ungültig - 402 Payment Required — Funktion erfordert höhere Lizenz-Stufe - 403 Forbidden — Auth ok aber Scope reicht nicht - 404 Not Found — Ressource existiert nicht - 429 Too Many Requests — Rate-Limit erreicht (mit Retry-After-Header) - 5xx — Server-Fehler

OpenAPI-Spec¶

Die maschinenlesbare Spec liegt unter:

GET https://mailguard.example.com:3443/api/v1/openapi.yaml

Kein Auth nötig — die Spec selbst ist öffentlich. Importierbar in Postman, Insomnia, oder per OpenAPI-Generator für Client-Bibliotheken. Siehe OpenAPI-Spec.