Zum Inhalt springen
Developer

Authentifizierung

Mit Session-Token oder API-Zugang (JWT) an der REST-API von vynst (inwendo ERP) anmelden.

Jede Organisation hat ihre eigene Instanz von vynst (inwendo ERP) mit eigener Adresse, zum Beispiel https://verein.iw-erp.de. Alle Pfade dieser Dokumentation hängen an diese Adresse an. In den Codebeispielen steht dafür eure-instanz.iw-erp.de.

Die API kennt zwei Wege, sich anzumelden. Beide schicken ein Token als HTTP-Header mit.

Weg Header Wofür
API-Zugang (JWT) x-iw-jwt-token Server-zu-Server, Skripte, Integrationen
E-Mail-Login x-session-token Apps, in denen sich eine Person anmeldet

API-Zugang (JWT)

Für Integrationen ist ein API-Zugang der richtige Weg. Er gehört zu einem Benutzer, hat dessen Rechte und läuft nicht nach ein paar Stunden ab.

  1. In der Verwaltung von vynst unter Einstellungen → API einen API-Zugang anlegen und das Token kopieren.
  2. Das Token bei jeder Anfrage im Header x-iw-jwt-token mitschicken.
curl https://eure-instanz.iw-erp.de/api/base/api_access_token_test?mode=info \
  --header 'x-iw-jwt-token: <TOKEN>'

GET /api/base/api_access_token_test prüft das Token. Mit mode=info liefert der Aufruf außerdem den Benutzer und die verfügbaren Scopes. Die Endpunkte für API-Zugänge stehen unter Login und Sitzung.

E-Mail-Login (Session)

Meldet sich eine Person mit E-Mail und Passwort an, liefert POST /api/logins eine Session. Deren sessionid geht bei allen folgenden Anfragen im Header x-session-token mit. POST /api/logouts beendet die Session.

curl --request POST https://eure-instanz.iw-erp.de/api/logins \
  --header 'content-type: application/json' \
  --data '{"login": {"username": "lena.hartmann@example.org", "password": "…"}}'

Ist für das Konto die Zwei-Faktor-Anmeldung aktiv, muss die Session danach mit GET /api/session/verify2fa/{id}/{code} bestätigt werden.

Rechte

Jeder Aufruf läuft mit den Rechten des Benutzers, zu dem das Token gehört. Fehlt ein Recht, antwortet die API mit 403. Gebt API-Zugängen deshalb nur die Rechte, die die Integration wirklich braucht.

OAuth für MCP und externe Dienste

Für KI-Assistenten (MCP) und Dienste wie Claude oder ChatGPT gibt es einen OAuth-Ablauf mit Freigabe durch die Person. Die Anleitung dazu folgt im Bereich Integrationen.