API & Integrationen

Für Entwickler

Dieser Bereich richtet sich an Entwicklerinnen und Entwickler, die Leitstand programmatisch anbinden wollen – etwa eine CI-Pipeline, einen ERP-Abgleich oder ein eigenes Reporting. Die übrigen Kapitel beschreiben die tägliche Arbeit in der Oberfläche; hier geht es um die API dahinter.

Leitstand stellt seine gesamte Funktionalität über eine REST-API unter /v1 bereit. Diese API kannst du aus eigenen Programmen ansprechen – mit denselben Möglichkeiten, die du auch in der Weboberfläche hast.

Dieselbe API wie das Frontend

Das ist der wichtigste Punkt für jede Integration: Es gibt keine zweite, separate API für Integrationen. Die Weboberfläche (das React-Frontend) ist selbst nur ein Client der /v1-API.

Jede Aktion, die du im Browser ausführst – eine Applikation anlegen, die Landschaft laden, das Dashboard öffnen – ist im Hintergrund ein HTTP-Aufruf gegen genau dieselben /v1-Endpunkte, die auch deiner Integration offenstehen.

   Weboberfläche (SPA)  ─┐
                         ├──►  Authorization: Bearer <IdToken>  ──►  /v1-API
   Deine Integration    ─┘

Daraus folgt unmittelbar:

• Was die Oberfläche kann, kann auch deine Integration – im Rahmen ihrer Rolle. Es gibt keine Funktion, die exklusiv „nur im Frontend" verfügbar wäre.
• Das Authentifizierungsmodell ist identisch. Frontend wie Integration schicken ein Cognito-ID-Token im Authorization: Bearer-Header. Derselbe JWT-Authorizer und dieselbe Tenant-/Rollenprüfung greifen.
• Die /v1-Endpunkte sind die Referenz. Willst du wissen, welche Felder ein Objekt hat, kannst du im Browser die Netzwerk-Aufrufe der Oberfläche beobachten – sie sind deckungsgleich mit dem, was deine Integration sieht.

Der einzige Unterschied liegt darin, wie das Token entsteht: Das Frontend holt es beim interaktiven Login (Mensch mit E-Mail + Passwort), deine Integration holt es mit den Credentials eines technischen Users (Maschine).

Technische User

Ein technischer User ist ein Maschinen-Account deines Mandanten (Tenants). Er besitzt eigene Credentials (username + secret) und eine Rolle – aber keine Person dahinter und keine E-Mail-Anmeldung.

Rolle	Lesen	Schreiben (POST/PUT/DELETE)
viewer	✅	❌
editor	✅	✅

Technische User können nicht die Rolle admin erhalten – eine Integration verwaltet also nie Nutzer oder andere technische User.

Alle Aufrufe eines technischen Users sind automatisch auf den Tenant beschränkt, in dem er angelegt wurde. Du musst (und kannst) den Tenant nicht im Request mitgeben – er steckt im Token.

In zwei Schritten zur Integration

1. Technischen User anlegen – einmalig in der Oberfläche unter System → Integrationen (nur für Admins). Du erhältst dabei username und secret.
2. Die API nutzen – mit diesen Credentials ein Token holen und damit die /v1-Endpunkte aufrufen.