🔐 API‑Authentifizierung & Fehlercodes

🔍 Inhalt

• Voraussetzungen
• Authentifizierung (HTTP Basic Auth)
• Beispiele nach Tool (cURL, Postman, Power Automate, Python)
• Media Types (Content‑Type & Accept)
• Fehlercodes & Ursachen
• Troubleshooting‑Checkliste
• FAQ

Voraussetzungen

• 🔐 Dedizierter API‑Benutzer je Mandant (Tenant). Nicht mitarbeiterindividuell.
  ℹ️ Hinweis: Änderungen am API-Benutzer (z. B. Passwortänderungen) können nur über den ValueStreamer Support erfolgen.

• 🌐 Nur HTTPS: https://api-<tenant>.valuestreamer.de/api/

• 🧪 Tool zur Request‑Ausführung (z. B. Postman, Swagger UI, Power Automate, Python, ...).

---

Authentifizierung (HTTP Basic Auth)

Die REST API verwendet HTTP Basic Auth. Benutzername und Passwort werden Base64‑kodiert im Authorization‑Header übertragen.

Header‑Beispiel:

Authorization: Basic <Base64(username:password)>

✨ Tipp: Testen Sie die Anmeldedaten zuerst mit einem einfachen GET (z. B. /exchange/teams).

⚠️ Achtung: Es gibt kein Ablaufdatum für den API‑Benutzer. Behandeln Sie Zugangsdaten dennoch wie Secrets.

🧰 Beispiele nach Tool

cURL

curl -X GET \
  "https://api-<tenant>.valuestreamer.de/api/exchange/teams" \
  -H "Authorization: Basic <BASE64>" \
  -H "Accept: application/json"

Postman

• Auth → Type: Basic Auth → Username/Password eintragen.

• Headers → Accept/Content-Type nach Endpunkt setzen (siehe unten).

Power Automate (HTTP‑Aktion)

• Methode, URL eintragen.

• Kopfzeilen: Authorization: Basic <BASE64>, Content-Type: …, Accept: …

• Körper: JSON gemäß Endpunkt‑Schema.

Python (requests)

import requests
from requests.auth import HTTPBasicAuth

url = "https://api-<tenant>.valuestreamer.de/api/exchange/teams"
r = requests.get(url, auth=HTTPBasicAuth("<USER>", "<PASS>"))
print(r.status_code, r.json())

🏷️ Media Types (Content‑Type & Accept)

Die API verwendet versionsspezifische Media Types. Richten Sie Accept und ggf. Content‑Type am jeweiligen Modul aus:

Modul / Kontext	Accept / Content‑Type
KPI v2	application/vs.v2.0+json
List Editor v2	application/vs.v2.0+json
Prozessboard v1	application/vs.pb.v1.0.0+json
Taskboard v1	application/json (falls nicht anders angegeben)
Deviation / Countermeasures v1	i. d. R. application/json bzw. modul­spezifische Varianten

✨ Tipp: In den YAML‑Spezifikationen je Modul sind die exakten Media Types pro Endpunkt ausgewiesen.

🚦 Fehlercodes & Ursachen

Antworten folgen dem Standard‑Schema (Beispiel):

{
  "errorId": 0,
  "errorMessage": "string"
}

Code	Bedeutung	Typische Ursache	Lösung
200/201	OK / Created	Request korrekt	—
204	Record deleted	Löschvorgang erfolgreich, kein Body	—
400	Bad Request	Ungültiger Body, fehlende Felder, falsche UUID/Datentyp	Request‑Schema gegen YAML prüfen; Pflichtfelder setzen; Datentypen korrigieren
401	Not authorized	Falsche/fehlende Basic‑Auth	Benutzer/Passwort prüfen; Base64 korrekt? Nur HTTPS verwenden
404	Not found	Ressource/ID existiert nicht oder falscher Pfad	IDs/URL prüfen; vorher GET auf Meta‑Endpunkte ausführen
409	Conflict	Regel verletzt (z. B. Duplikat, ungültiger Zustand)	Payload anpassen; Geschäftsregeln in Artikel/YAML beachten
415	Unsupported Media Type	Falscher Content-Type/Accept	Media Type laut Modul setzen (Tabelle oben)
422	Unprocessable Entity	Valide JSON, aber fachlich inkonsistent	Pflichtbeziehungen/Validierungen prüfen (z. B. Status/Message)
500	Internal Server Error	Unerwarteter Fehler	Request minimieren, später erneut versuchen; Support mit errorId, Zeitstempel & Payload kontaktieren

ℹ️ Hinweis: Nicht jeder Endpunkt nutzt alle Codes; maßgeblich ist die jeweilige OpenAPI‑Spezifikation (YAML/Swagger).

🧭 Troubleshooting‑Checkliste

1. Auth korrekt? Basic Auth aktiv, Base64 ohne Zeilenumbruch.

2. HTTPS? Nur https:// zulässig.

3. Media Types stimmen (Accept/Content‑Type).

4. Pflichtfelder laut YAML gesetzt?

5. IDs validieren (Team/KPI/List/Phase etc. per Meta‑GET holen).

6. Geschäftsregeln beachten (z. B. Statuswechsel benötigt statusMessage).

7. Minimal‑Payload testen, dann Felder schrittweise ergänzen.

8. Fehlerdetails dokumentieren: status, errorId, errorMessage, Zeitstempel, Anfrage‑ID (falls vorhanden).

❓ FAQ

Gibt es individuelle API‑Benutzer pro Mitarbeiter?
Nein. Jeder Mandant hat einen dedizierten API‑Benutzer. Personenbezogene Logins sind für API‑Zugriffe nicht vorgesehen.

Unterstützt die API Webhooks oder Token‑basierte Auth?
Aktuell nein. Es wird ausschließlich HTTP Basic Auth über HTTPS unterstützt.

Wo finde ich die vollständigen Fehlercodes und Media Types?
In den YAML‑Dateien der jeweiligen Module; außerdem sind Beispiel‑Responses in Swagger/der PDF‑Doku sichtbar.

Warum erhalte ich 401 trotz korrekter Zugangsdaten?
Meist fehlt der Header ganz oder die Base64‑Kodierung enthält Sonderzeichen/Whitespace. In Postman Basic Auth verwenden (nicht selbst kodieren).

Wann verwende ich 415 vs. 400?
415 = Header/Format falsch; 400 = Format korrekt, aber Inhalt/Schema fehlerhaft.