ImmoMgmt Anmelden Kostenlos testen
Zurück zur Startseite

Für Entwicklerinnen und Entwickler

API & Integrationen

Alles, was du für die Anbindung eigener Systeme an ImmoMgmt brauchst: Authentifizierung per Personal Access Token, Beispiele, das OpenAPI-Schema, Rate-Limits und Sperrverhalten sowie der lesende MCP-Zugang.

Überblick

Die ImmoMgmt-API ist eine REST-Schnittstelle über HTTPS. Alle produktiven Endpunkte liegen unterhalb von /api/v1/ und liefern JSON. Jede Anfrage ist authentifiziert und immer auf genau einen Mandanten begrenzt.

Diese Seite ist der Einstieg. Die vollständige, maschinenlesbare Referenz aller Endpunkte, Felder und Fehlercodes steht im OpenAPI-Schema und in der interaktiven Swagger-UI.

Authentifizierung: Personal Access Token

Für externe Integrationen ist der Personal Access Token (PAT) der einzige empfohlene Weg. Ein PAT wird im eingeloggten Konto unter „Einstellungen → API-Zugänge“ erzeugt, ist an genau eine Nutzerin bzw. einen Nutzer und deren Mandanten gebunden und wird bei der Erstellung genau einmal im Klartext angezeigt.

Ein Token beginnt immer mit dem Präfix immopat_ und wird als Bearer-Token im HTTP-Header mitgeschickt:

Authorization: Bearer immopat_XXXXXXXX_DEIN_TOKEN

Wir speichern ausschließlich einen Hash des Tokens. Ein verlorenes Token kann deshalb nicht wiederhergestellt, sondern nur ersetzt werden. Übertrage Tokens niemals in URLs, Query-Parametern, Log-Dateien oder Screenshots — ausschließlich im Authorization-Header.

Die JWT-Anmeldung existiert weiterhin, ist aber ausschließlich für unsere eigene mobile App gedacht und wird für externe Integrationen ausdrücklich nicht empfohlen: JWTs sind kurzlebig, an einen Login-Flow gebunden und bieten weder feingranulare Berechtigungen noch einen sauberen Widerruf einzelner Integrationen.

Token-Lebenszyklus: Scope, Ablauf, Rotation, Widerruf

Scope
Jedes Token erhält bei der Erstellung einen Scope. Lesende Integrationen bekommen ausschließlich Lese-Scopes; schreibende Rechte werden nur vergeben, wenn die Integration sie wirklich braucht. Der Scope kann nachträglich nicht erweitert werden — dafür wird ein neues Token erstellt.
Ablauf
Tokens haben ein Ablaufdatum. Nach Ablauf werden Anfragen mit HTTP 401 abgelehnt. Vor dem Ablauf informieren wir die Eigentümerin bzw. den Eigentümer des Tokens per E-Mail, damit die Integration nicht unbemerkt stehen bleibt.
Rotation
Für die Rotation wird ein zweites Token erzeugt, in der Integration hinterlegt und erst danach das alte Token widerrufen. So entsteht kein Ausfallfenster. Wir empfehlen eine planmäßige Rotation mindestens einmal jährlich sowie sofort bei jedem Verdacht auf Kompromittierung.
Widerruf
Jedes Token kann jederzeit im Konto widerrufen werden. Der Widerruf wirkt sofort für alle folgenden Anfragen. Zusätzlich zeigen wir je Token den Zeitpunkt der letzten Nutzung, damit ungenutzte Tokens erkannt und entfernt werden können.

curl-Beispiele

Ersetze den Platzhalter durch dein eigenes Token. Die hier gezeigten Werte sind bewusst keine gültigen Tokens.

Gebäude auflisten:

curl -H "Authorization: Bearer immopat_XXXXXXXX_DEIN_TOKEN" \
     -H "Accept: application/json" \
     https://immomgmt.cloud/api/v1/buildings/

Antwort-Header eines Rate-Limit-Fehlers ansehen:

curl -i -H "Authorization: Bearer immopat_XXXXXXXX_DEIN_TOKEN" \
     https://immomgmt.cloud/api/v1/buildings/

Bei erfolgreicher Authentifizierung antwortet die API mit HTTP 200 und einer paginierten JSON-Liste. Ein fehlendes oder ungültiges Token führt zu HTTP 401, ein fehlender Scope zu HTTP 403.

OpenAPI-Schema & Swagger-UI

Die vollständige Referenz wird direkt aus dem Code erzeugt und ist damit immer aktuell:

Aus dem Schema lassen sich mit den üblichen Generatoren typisierte Clients erzeugen. Das Schema ist die verbindliche Quelle für Feldnamen, Pflichtfelder und Fehlerformate.

Rate-Limits & Sperrverhalten

Damit die Plattform für alle stabil bleibt, gelten Rate-Limits. Wird ein Limit überschritten, antwortet die API mit HTTP 429 und dem Header Retry-After, der die Wartezeit in Sekunden angibt. Ein korrekt implementierter Client wartet diese Zeit ab, statt sofort erneut anzufragen.

Anonym
60 Anfragen pro Minute
Angemeldete Nutzer (Session/JWT)
300 Anfragen pro Minute
Personal Access Token
120 Anfragen pro Minute
Burst-Schutz
zusätzlich 30 Anfragen pro Minute und 600 Anfragen pro Stunde je IP-Adresse

Bei wiederholten Fehlversuchen — etwa fortlaufend ungültigen Tokens — greift ein exponentielles Backoff: Die erzwungene Wartezeit verdoppelt sich mit jedem weiteren Fehlversuch, bevor eine temporäre Sperre der Quelle greift. Die Sperre endet automatisch nach Ablauf des Zeitfensters.

Fällt ein einzelnes Token durch auffälliges Verhalten auf — sehr viele 401/403-Antworten, extreme Anfrageraten oder Zugriffsmuster, die auf Missbrauch hindeuten — wird es automatisch deaktiviert. Die Eigentümerin bzw. der Eigentümer wird per E-Mail informiert; die Integration muss dann mit einem neu erstellten Token wieder in Betrieb genommen werden.

Für den Notfall existiert zusätzlich ein Kill-Switch: Damit lässt sich der API-Zugang eines Mandanten oder die gesamte externe Schnittstelle sofort abschalten, ohne dass die Weboberfläche beeinträchtigt wird.

Bitte plane Integrationen so, dass sie 429-Antworten respektieren, Anfragen bündeln und nicht in engen Schleifen pollen. Wer regelmäßig größere Datenmengen braucht, kontaktiert uns besser vorab, statt das Limit auszureizen.

Mandanten-Trennung

Jedes Token gehört zu genau einem Mandanten. Die API liefert ausschließlich Daten dieses Mandanten; eine mandantenübergreifende Abfrage ist technisch nicht möglich. Die Trennung wird serverseitig erzwungen und nicht über Filterparameter des Clients gesteuert.

Wer mehrere Mandanten anbinden möchte, erstellt je Mandant ein eigenes Token. Objekte aus einem fremden Mandanten sind nicht sichtbar und werden mit HTTP 404 beantwortet — bewusst nicht mit 403, damit die Existenz fremder Datensätze nicht verraten wird.

Versionierung & Deprecation-Policy

Die Version steht im Pfad: /api/v1/. Innerhalb einer Version nehmen wir nur abwärtskompatible Änderungen vor, etwa neue Felder oder neue Endpunkte. Clients müssen daher unbekannte Felder tolerieren.

Breaking Changes erscheinen in einer neuen Version. Wird ein Endpunkt abgekündigt, markieren wir ihn im OpenAPI-Schema als deprecated und senden die Header Deprecation und Sunset mit dem geplanten Abschaltdatum. Zwischen Ankündigung und Abschaltung liegen mindestens sechs Monate.

MCP-Zugang für KI-Assistenten

Zusätzlich zur REST-API bieten wir einen MCP-Endpunkt (Model Context Protocol) an. Darüber können KI-Assistenten strukturiert auf deine Daten zugreifen, ohne dass du Screenshots oder Exporte hin- und herschiebst.

Endpunkt
/mcp/
Protokoll
JSON-RPC 2.0 über HTTPS
Authentifizierung
derselbe Personal Access Token wie bei der REST-API, als Bearer-Token im Authorization-Header
Umfang
ausschließlich lesende Tools — der MCP-Gateway kann keine Daten anlegen, ändern oder löschen

Für den MCP-Zugang gelten dieselben Regeln wie für die REST-API: Mandanten-Trennung, Scopes, Rate-Limits und Sperrverhalten. Ein Widerruf des Tokens beendet auch den MCP-Zugriff sofort.

Fragen & Kontakt

Fragen zur Anbindung, zu Limits oder zu einem geplanten Integrationsprojekt beantworten wir gerne.

Zum Kontaktformular

Sicherheitsrelevante Funde bitte nicht öffentlich posten, sondern vertraulich melden. Wenn du versehentlich ein Token offengelegt hast: sofort widerrufen und ein neues erstellen.