API-Dokumentation

Vollständige REST API-Referenz mit curl-Beispielen

REST API v1
Zugriff auf alle Ressourcen über HTTP
Base URL: /api/v1
Authentifizierung
Session-basiert mit httpOnly Cookies
Nach Login automatisch gesetzt
RBAC
Rollenbasierte Zugriffskontrolle pro Modul
Keine zusätzlichen Header erforderlich

Authentifizierung

Benutzer-Authentifizierung und Session-Verwaltung. Login und Registrierung sind oeffentlich zugaenglich, alle anderen Endpunkte erfordern eine aktive Session.

Base: /api/v1/authpublic
POST/api/v1/auth/login
Benutzer anmelden
Authentifiziert einen Benutzer mit E-Mail und Passwort. Setzt ein httpOnly Session-Cookie. Rate-Limit: max 10 Versuche pro Minute pro IP.

cURL

curl -X POST https://example.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -c cookies.txt \
  -d '{"email":"max@mustermann-gmbh.de","password":"sicheresPasswort123!"}'
POST/api/v1/auth/register
Neues Konto registrieren
Erstellt einen neuen Admin-Benutzer. Seeded Default-Rollen und strukturelle Daten (idempotent). Setzt automatisch ein Session-Cookie. Rate-Limit: max 5 Registrierungen pro Minute pro IP.

cURL

curl -X POST https://example.com/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -c cookies.txt \
  -d '{"email":"lisa@weber-consulting.de","password":"meinPasswort456!","firstName":"Lisa","lastName":"Weber","companyName":"Weber Consulting GmbH"}'
POST/api/v1/auth/logout
Abmelden
Loescht die aktive Session und das Session-Cookie.

cURL

curl -X POST https://example.com/api/v1/auth/logout \
  -b cookies.txt
GET/api/v1/auth/me
Aktuelle Authentifizierung abrufen
Liefert Informationen ueber die aktuelle Authentifizierung. Akzeptiert sowohl Session-Cookies als auch x-api-key-Header. Bei Session-Auth wird der eingeloggte Benutzer zurueckgegeben (auth: "session"); bei API-Key-Auth die Key-ID + Permissions (auth: "api-key"). 401 nur, wenn weder gueltige Session noch gueltiger API-Key vorhanden ist.

cURL

# Variante A: Session-Cookie
curl https://example.com/api/v1/auth/me \
  -b cookies.txt

# Variante B: API-Key
curl https://example.com/api/v1/auth/me \
  -H "x-api-key: xkmu_<dein-key>"
GET/api/v1/auth/permissions
Berechtigungen abrufen
Gibt die CRUD-Berechtigungen des aktuellen Benutzers pro Modul zurueck. Owner und Admin erhalten immer vollen Zugriff. Andere Rollen laden Berechtigungen aus der Datenbank oder nutzen Legacy-Fallback-Defaults.

cURL

curl https://example.com/api/v1/auth/permissions \
  -b cookies.txt
POST/api/v1/auth/change-password
Passwort aendern
Aendert das Passwort des aktuell eingeloggten Benutzers. Das aktuelle Passwort muss zur Verifikation mitgesendet werden.

cURL

curl -X POST https://example.com/api/v1/auth/change-password \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{"currentPassword":"altesPasswort123!","newPassword":"neuesSicheresPasswort456!"}'