JTL Wawi REST API 401 Unauthorized Ursachen und Lösung
JTL-Administrator Oberfläche mit REST API Dienst-Konfiguration und 401 Fehlermeldung im Terminal

JTL Wawi REST API 401 Unauthorized: Ursachen und wie du sie behebst

Du rufst die JTL-Wawi REST API auf, der API-Key ist korrekt eingetragen, und trotzdem kommt `401 Unauthorized` zurück. Kein Einzelfall. Im JTL-Forum taucht das Problem regelmäßig auf, vor allem nach Updates auf Wawi 2.0 oder beim ersten Einrichten der OnPrem-Instanz. Die Ursachen sind fast immer dieselben fünf, und alle lassen sich beheben. Hier erfährst du was dahintersteckt und wie du den Fehler systematisch eingrenzt.

Du hast alles konfiguriert und bekommst trotzdem 401 zurück?

Dann fehlt vermutlich einer dieser fünf Punkte. Wir sehen das regelmäßig bei Kunden, die die REST API neu einrichten oder nach einem Wawi-Update plötzlich keine Verbindung mehr bekommen.

Von Alexander Luft · JTL-Wawi / API · April 2026

Auf einen Blick

  • ✓Ein `401 Unauthorized` bei `Authorization: Wawi ` heißt fast immer: falsche Key-Quelle, fehlende App-Benutzer-Zuweisung oder der REST-API-Dienst im JTL-Administrator läuft gar nicht. Vlarom sieht das Muster regelmäßig bei API-Einrichtungen.
  • ✓Nach dem Update auf JTL-Wawi 2.0 liefern v2-Endpunkte mit `/v2/` im Pfad `400 UnsupportedApiVersion`. Der saubere Weg ist der `api-version`-Header oder weiter `/v1/`, bis v2 vollständig stabil ist.
  • ✓Vlarom-Tipp als JTL Service Partner Gold: Erst den Info-Endpunkt `GET /api/eazybusiness/info` testen. Kommen korrekte Daten zurück, läuft der Dienst und der Fehler liegt in der Auth-Kette.

Die REST API von JTL-Wawi ist technisch solide. Der Einrichtungsprozess hat allerdings mehrere Sicherheitsstufen, die in der Dokumentation nicht immer klar beschrieben sind. Wenn Kunden mit „der API-Key ist doch korrekt, warum geht es nicht?“ zu uns kommen, liegt der Fehler in 90% der Fälle im Registrierungsablauf oder in einem Dienst, der nicht läuft. Das ist in wenigen Minuten behoben, wenn man weiß wo man sucht.

Wie verbreitet ist das Problem — was zeigen Forum-Daten?

Aus der Auswertung mehrerer JTL-Forum-Threads und eigener Projektdaten liegen uns aktive Threads allein zu `401 Unauthorized` und `Authorization: Wawi ` aus den letzten Monaten vor. Seit dem Release von JTL-Wawi 2.0 Stable ab 17.03.2026 kommen Fragen zu v2-Endpunkten dazu. Die API selbst ist technisch stabil. Die Probleme entstehen fast immer beim Einrichten, nicht im Betrieb.

Quelle Vlarom-Projektdaten: In den Forum-Threads zu `REST API 401` zeigen sich drei Hauptmuster: (1) App-Benutzer-Zuweisung fehlt beim Registrierungsabschluss, (2) REST-API-Dienst im JTL-Administrator ist angelegt, aber nicht gestartet, (3) nach Wawi 2.0-Update werden v2-Pfade genutzt, die der Server noch nicht kennt. Alle drei Muster lassen sich ohne Neuinstallation lösen.

Diese Faktoren machen aus einem kurzen Einrichtungsprozess eine stundenlange Fehlersuche:

  • →Registrierungsablauf hat mehrere Schritte: Die App-Registrierung über POST /api/eazybusiness/v1/authentication liefert Status 201. Das ist aber erst Schritt eins. Ohne Genehmigung in der Wawi-Benutzerverwaltung und Benutzer-Zuweisung bleibt der API-Key wirkungslos.
  • →Zwei verschiedene Keys im Umlauf: JTL gibt beim Registrierungsablauf einen App-Registration-Key zurück. Der eigentliche User-API-Key kommt erst beim ersten GET auf /authentication/ im Feld Token.ApiKey. Wer den falschen Key nimmt, bekommt immer 401.
  • →v1 und v2 verhalten sich unterschiedlich: Mit /v2/ im URL-Pfad liefert der Server 400 UnsupportedApiVersion, sobald die Wawi-Version v2 noch nicht vollständig unterstützt. Mit dem Header api-version: 2 funktioniert v2-Lesen dagegen auf vielen Installationen. Schreib-Endpunkte in v2 sind noch nicht überall stabil.
  • →Dienst-Konfiguration überlebt Windows-Updates nicht immer: Ein Windows-Server-Update stoppt manchmal den REST-API-Dienst im JTL-Administrator. Dann hilft ein manueller Neustart oder die Konfiguration als automatisch startender Windows-Dienst.

Das zentrale Muster: Ein `401 Unauthorized` ist fast nie ein Fehler im API-Key selbst. Er ist ein Signal, dass ein Schritt im Einrichtungsprozess übersprungen wurde oder nach einem Update zurückgesetzt ist.

Die 5 häufigsten Ursachen für 401 Unauthorized

Aus Forum-Threads und Kundenprojekten kristallisieren sich fünf Muster heraus, die den Großteil aller 401-Fehler erklären. Wir gehen sie der Häufigkeit nach durch.

1

Falscher API-Key verwendet

Die Registrierung über POST /api/eazybusiness/v1/authentication liefert einen Registration-Key. Das ist nicht der finale Key für API-Calls. Der eigentliche User-API-Key kommt erst beim ersten GET /api/eazybusiness/v1/authentication/ im Feld Token.ApiKey.

Ein Händler im JTL-Forum: ‚Der API-Key wird beim ersten GET auf /authentication/ im Token.ApiKey Feld zurückgegeben, aber jeder Request mit diesem Key gibt trotzdem 401.' Ursache war die fehlende Benutzer-Zuweisung.

2

App hat keinen Wawi-Benutzer zugewiesen

Damit Authorization: Wawi funktioniert, muss die registrierte App in der Wawi-Benutzerverwaltung einem Benutzer zugeordnet sein. Fehlt die Zuweisung, bleibt der Registrierungsstatus offen und alle Anfragen laufen in 401.

Ein Händler im JTL-Forum: ‚Hat sich erledigt, klappt nun. Denke das Problem lag daran, dass der App bei Registrierung ein Wawi-Benutzer zugeordnet werden muss. Dieser existierte aber schon bei uns und das hat vermutlich den Fehler verursacht.‘ Doppelte Benutzer-Einträge blockieren die Zuweisung.

Was du gewinnst, wenn die API sauber läuft

Vollautomatische Auftragsverarbeitung ohne Workaround

Aufträge, Kunden und Artikel lassen sich programmatisch anlegen und aktualisieren. Ohne Worker-Umwege, ohne Batch-Fenster. Bei einem Kunden haben wir die tägliche Nacharbeit durch API-Automatisierung auf unter 30 Minuten reduziert. Der erste Schritt ist immer: den 401-Fehler aus dem Weg räumen.

Saubere Systemintegration statt Copy-Paste zwischen Tools

Wer mehrere Systeme (Shop, ERP, Marktplatz) mit JTL-Wawi verbinden will, braucht eine verlässliche API-Basis. Als JTL Service Partner Gold entwickeln wir maßgeschneiderte API-Konnektoren für genau diese Anforderungen. Das innocigs.com-Projekt zeigt, was möglich ist, wenn die API-Verbindung sauber steht.

Die Lektion

Vlarom-Erkenntnis aus API-Projekten: Die JTL REST API hat bewusst mehrere Sicherheitsstufen beim Einrichten. Damit bekommt nicht jede beliebige App Zugriff. Wer den Ablauf einmal verstanden hat (Registrierung, Genehmigung, Benutzer-Zuweisung, Key abrufen), hat danach keine Probleme mehr.

Dein 5-Schritte-Plan gegen den 401-Fehler

Der Plan geht von außen nach innen vor: erst prüfen, ob der Dienst läuft, dann die Netzwerkkonfiguration, dann den Auth-Ablauf. So sparst du dir die häufigste Zeitfalle: stundenlang am API-Key schrauben, während der Dienst gar nicht läuft.

Info-Endpunkt testen (5 Minuten)

„Ruf GET /api/eazybusiness/info ohne Authentication-Header auf. Antwortet der Endpunkt und liefert Version sowie Tenant-Name zurück, läuft der Dienst und das Problem liegt in der Auth-Kette. Kommt keine Antwort, ist Schritt 2 zuerst dran. Die JTL-Guide-Seite zur API-Einrichtung beschreibt den Info-Endpunkt als öffentlich erreichbar.“

Dienst-Status im JTL-Administrator prüfen (5 Minuten)

„Öffne den JTL-Administrator, wähle die REST-API-Instanz und prüfe den Status im Tab Dienste. Steht dort nicht Läuft, muss der Dienst manuell gestartet werden. Für dauerhaft stabilen Betrieb: die Instanz mit der Option Als Dienst anlegen konfigurieren, damit Windows-Updates den Dienst nicht stoppen. Standardport ist 5883.“

App-Registrierung und Benutzer-Zuweisung prüfen (10 Minuten)

„Öffne in JTL-Wawi die Benutzerverwaltung und prüfe, ob deine registrierte App einem Benutzer zugewiesen ist. Der Registrierungsstatus muss auf 2 stehen (genehmigt und zugewiesen), nicht auf 1 (genehmigt, aber kein Benutzer). Das ist der häufigste Fehler: App genehmigt, Benutzer-Zuweisung fehlt. Das gibt immer 401, unabhängig vom Key.“

Den richtigen API-Key verwenden (5 Minuten)

„Nach abgeschlossener Registrierung einmalig GET /api/eazybusiness/v1/authentication/ aufrufen. Im Feld Token.ApiKey steht der finale Key für den Authorization-Header als Authorization: Wawi . Nicht den Registration-Key verwenden, den der initiale POST zurückgibt. Weitere Details in der JTL-Wawi API Dokumentation im JTL-Guide."

v1 vs. v2: die richtige Version wählen (5 Minuten)

„Wenn du v2-Endpunkte nutzen willst, verwende den Header api-version: 2 statt /v2/ im URL-Pfad. /v2/ im Pfad liefert auf vielen Installationen noch 400 UnsupportedApiVersion. Für produktive Systeme gilt aktuell: v1-Endpunkte sind stabil und vollständig unterstützt. v2-Lesen funktioniert über den Header, v2-Schreib-Endpunkte sind noch nicht auf allen Wawi-Versionen vollständig stabil.“

Häufig gestellte Fragen zu JTL Wawi REST API 401

Was bedeutet 401 Unauthorized bei der JTL REST API genau?

401 Unauthorized bedeutet, dass der REST-API-Server die Anfrage empfangen hat, die Identität des Aufrufers aber nicht verifizieren konnte. Das kann an einem falschen oder abgelaufenen API-Key liegen, an einer fehlenden Benutzer-Zuweisung in der Wawi-Benutzerverwaltung oder daran, dass der Authorization-Header falsch formatiert ist. Das korrekte Format lautet Authorization: Wawi . Ein 401 bedeutet nicht, dass der Dienst nicht läuft — das wäre ein Verbindungsabbruch oder 503.

Eine registrierte App allein reicht nicht — sie muss in JTL-Wawi einem Benutzer zugewiesen sein. Wenn der Registrierungsstatus auf 1 steht (genehmigt) aber kein Benutzer zugeordnet ist, liefert jede Anfrage 401. Öffne in JTL-Wawi die Benutzerverwaltung und weise der App explizit einen Wawi-Benutzer zu. Danach den finalen API-Key neu über GET /api/eazybusiness/v1/authentication/ abrufen und erneut testen.

Es gibt zwei verschiedene Keys im Registrierungsablauf. Der Registration-Key kommt als Antwort auf POST /api/eazybusiness/v1/authentication — das ist der Schlüssel für den Registrierungsprozess selbst, nicht für spätere API-Calls. Der eigentliche User-API-Key steht im Feld Token.ApiKey, den du beim ersten GET /api/eazybusiness/v1/authentication/ nach Abschluss der Registrierung bekommst. Nur dieser Key funktioniert im Authorization-Header für reguläre API-Calls.

400 UnsupportedApiVersion tritt auf, wenn du /v2/ direkt im URL-Pfad verwendest und dein REST-API-Server diese Version noch nicht vollständig unterstützt. Der aktuell zuverlässige Weg: Entweder weiter /v1/ im Pfad nutzen, oder den Header api-version: 2 für Lese-Endpunkte verwenden. /v2/ im Pfad ist auf vielen Installationen noch nicht stabil — das bestätigen mehrere Forum-Berichte zu Wawi 1.11.7 und 2.0.

Windows-Updates können Dienste stoppen, die nicht als automatisch startende Windows-Dienste konfiguriert sind. Im JTL-Administrator muss die REST-API-Instanz mit der Option Als Dienst anlegen eingerichtet sein — dann startet sie automatisch nach Reboots. Wurde die Instanz ohne diese Option angelegt, muss sie manuell neu gestartet werden. Die Fehlermeldung lautet dann: Der Rest-Server konnte nicht gestartet werden. Bitte überprüfe die Serverkonfiguration in den Globalen Einstellungen.

Ruf den Info-Endpunkt ohne Authentication-Header auf: GET http://[deine-ip]:5883/api/eazybusiness/info. Dieser Endpunkt gibt bei laufendem Dienst Wawi-Version und Tenant-Name zurück. Wenn er keine Antwort liefert, ist der Dienst gestoppt oder Port 5883 durch die Firewall blockiert. Für externe Anfragen muss die Windows-Firewall diesen Port freigeben.

Ein zeitlich verzögertes 401 nach funktionierender Verbindung deutet auf einen Key-Ablauf oder eine Sitzungsbegrenzung hin. Bei sehr hohem Request-Volumen auf /customers oder /salesOrders Endpunkten kann die JTL REST API mit 401 oder 502 antworten. Hilft es, den API-Key neu zu generieren und parallele Requests zu reduzieren. Außerdem kann ein gestoppter Dienst nach einem Windows-Update dieses Symptom verursachen — Dienst-Status im JTL-Administrator prüfen.

Eine Swagger UI ist bei laufendem Dienst unter /api/eazybusiness/swagger erreichbar. Auf einigen Installationen ist dieser Pfad nicht zugänglich (404) — das ist ein bekanntes Problem laut JTL-Forum. Als Alternative gibt es die offizielle Entwickler-Dokumentation auf developer.jtl-software.com, die Endpunkte, Request-Schemas und Auth-Abläufe beschreibt.

REST API macht Probleme? Wir schauen uns das an.

Mit Vlarom die JTL REST API sauber anbinden.

Wir entwickeln als JTL Service Partner Gold maßgeschneiderte API-Konnektoren und richten REST-API-Verbindungen für JTL-Wawi ein. Wenn du die Fehlersuche nicht alleine durchziehen willst, ruf uns direkt an unter +49 30 91473862, schreib an info@vlarom.de oder nutze unser Kontaktformular für eine unverbindliche Erstanalyse.