Public API (v1)

Programmatischer Zugriff auf PropMind über eine versionierte REST-API mit API-Key-Authentifizierung und Webhooks. Die vollständige, interaktive Endpunkt-Referenz liegt unter prop-mind.de/api/docs (ReDoc, OpenAPI 3.1).

Authentifizierung

Jeder v1-Request trägt einen API-Key als Bearer-Token:

curl https://prop-mind.de/api/v1/ping \
  -H "Authorization: Bearer pm_live_…"

• Keys werden im Admin-Bereich unter Einstellungen → API-Keys erzeugt.
• Der Klartext-Key wird einmalig bei der Erstellung angezeigt und danach nie wieder — sicher speichern. Gespeichert wird nur ein SHA-256-Hash.
• Jeder Key trägt Scopes (Least-Privilege) und optional ein Ablaufdatum. Widerrufen ist jederzeit möglich (sofort wirksam).

Scopes

Scope	Erlaubt
properties:read	Objekte lesen (GET /v1/properties)
properties:write	Objekte anlegen/ändern (reserviert)
tenants:read	Mietverhältnisse lesen (reserviert)
invoices:read	Rechnungen lesen (reserviert)
webhooks:manage	Webhooks per API verwalten (reserviert)

Alle Daten sind mandantengebunden: ein Key sieht ausschließlich die Objekte der eigenen Firma. Rate-Limit: 120 Requests/Minute pro Key.

Endpunkte (Stand v1)

Methode	Pfad	Scope
GET	/api/v1/ping	— (nur gültiger Key)
GET	/api/v1/properties?limit=&offset=	properties:read
GET	/api/v1/properties/{id}	properties:read

Webhooks

Unter Einstellungen → Webhooks eine HTTPS-URL registrieren und Events abonnieren (oder * für alle).

Verfügbare Events (v1):

Event	Ausgelöst bei
property.created	Neues Objekt angelegt

(Weitere Events folgen; abonniere *, um automatisch alle zu erhalten.)

Bei jedem Event stellt PropMind einen signierten POST zu:

• Header X-PropMind-Event: Event-Name
• Header X-PropMind-Signature: sha256=<HMAC-SHA256(body, secret)>
• Body: { "event": "...", "createdAt": "...", "data": { ... } }

Das Secret wird bei der Registrierung einmalig angezeigt. Zustellungen mit Fehlercode werden mit exponentiellem Backoff bis zu 5× wiederholt (1, 5, 30, 120, 360 Minuten). Die letzten Zustellversuche sind pro Webhook einsehbar.

Signatur verifizieren (Beispiel Node.js)

import crypto from "node:crypto";

function verify(rawBody, signatureHeader, secret) {
  const expected = "sha256=" +
    crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signatureHeader));
}

Immer den rohen Request-Body (vor JSON-Parsing) für die HMAC-Prüfung verwenden.