Skip to content

API-Referenz

TCM365 stellt eine umfassende REST API zur Verwaltung von Multi-Vendor Tenant-Konfigurationen, Security Baselines, Compliance-Assessments und operativen Workflows bereit. Alle Endpoints folgen einheitlichen Konventionen für Authentifizierung, Request/Response-Format und Fehlerbehandlung.

Basis-URL

Alle API-Routen haben das Präfix /api/v1/ sofern nicht anders angegeben:

https://ihre-tcm365-instanz.de/api/v1/

Für lokale Entwicklung läuft das Backend auf Port 8000:

http://localhost:8000/api/v1/

Interaktive Dokumentation (Swagger UI)

TCM365 wird mit einer interaktiven Swagger UI zum Erkunden und Testen aller Endpoints ausgeliefert:

http://localhost:8000/api/docs

Swagger UI-Funktionen

Die Swagger UI umfasst Request/Response-Schemas, Authentifizierungsunterstuetzung (JWT-Token einfügen) und einen "Try it out"-Button für jeden Endpoint. Sie wird automatisch aus NestJS-Dekoratoren generiert und bleibt synchron mit dem Codebase.

Authentifizierung

Alle Endpoints ausser /health und /api/v1/auth/login erfordern ein gueltiges JWT Bearer Token. Token im Authorization-Header angeben:

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Token über POST /api/v1/auth/login mit E-Mail und Passwort erhalten. Siehe Authentifizierung für detaillierte Flow-Dokumentation.

Request- und Response-Format

Alle Request- und Response-Bodies verwenden JSON (Content-Type: application/json).

Standard-Erfolgsantwort

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Mein Snapshot",
  "createdAt": "2026-03-05T14:30:00.000Z"
}

Standard-Fehlerantwort

{
  "statusCode": 400,
  "message": "Validierung fehlgeschlagen",
  "error": "Bad Request"
}

Pagination

Listen-Endpoints unterstützen Pagination über Query-Parameter:

Parameter Typ Standard Beschreibung
page number 1 Seitennummer (1-basiert)
limit number 20 Anzahl Einträge pro Seite

Allgemeine Header

Request Header

Header Pflicht Beschreibung
Authorization Ja JWT Bearer Token für Authentifizierung
Content-Type Ja Muss application/json für Request Bodies sein
X-Request-ID Nein Korrelations-ID für Request-Tracing (auto-generiert wenn nicht angegeben)

Response Header

Header Beschreibung
X-Request-ID Korrelations-ID für Tracing (aus Request uebernommen oder auto-generiert)
X-Process-Time Request-Verarbeitungsdauer in Millisekunden

Request-Korrelation

Jedem Request wird eine X-Request-ID zugewiesen, die in Response-Headern und strukturierten Backend-Logs erscheint. Eigene X-Request-ID im Header übergeben um API-Calls mit der eigenen Monitoring-Infrastruktur zu korrelieren.

Rate Limiting

TCM365 implementiert Rate Limiting zum Schutz vor Missbrauch:

  • Primär: Redis-basierter Sliding-Window Rate Limiter (wenn Redis verfügbar)
  • Fallback: In-Memory Rate Limiter (wenn Redis nicht verfügbar)

Rate-Limit-Header sind in Responses enthalten:

Header Beschreibung
X-RateLimit-Limit Maximale Anfragen pro Fenster
X-RateLimit-Remaining Verbleibende Anfragen im aktuellen Fenster
X-RateLimit-Reset Zeitstempel wann das Fenster zurückgesetzt wird

Bei Rate Limiting gibt die API 429 Too Many Requests zurück.

HTTP-Statuscodes

Code Bedeutung Wann zurueckgegeben
200 OK Erfolgreicher GET, PUT, PATCH
201 Created Erfolgreicher POST der eine Ressource erstellt
204 No Content Erfolgreicher DELETE
400 Bad Request Validierungsfehler, fehlerhafter Request
401 Unauthorized Fehlendes oder abgelaufenes JWT Token
403 Forbidden Unzureichende Rolle oder Berechtigung
404 Not Found Ressource existiert nicht oder Tenant-Zugriff verweigert
409 Conflict Doppelte Ressource oder Zustandskonflikt
429 Too Many Requests Rate Limit überschritten
500 Internal Server Error Unbehandelter Serverfehler

Endpoint-Gruppen

Die folgende Tabelle listet alle API-Endpoint-Gruppen in TCM365 v2.5.0:

Gruppe Pfad Zweck
Authentifizierung /api/v1/auth Login, Logout, Token Refresh, Profil, Passwortänderung
Benutzer /api/v1/users Benutzer-CRUD-Verwaltung (nur Admin)
Tenants /api/v1/tenants Multi-Vendor Tenant-Verwaltung und Feature Flags
Snapshots /api/v1/snapshots Erstellen, Auflisten, Vergleichen und Bulk-Löschen von Snapshots
Blueprints /api/v1/blueprints Konfigurationsvorlagen-Verwaltung
Baselines /api/v1/baselines Security Baseline-Verwaltung und Compliance Engine
KI-Analyse /api/v1/ai-analysis KI-gestützte Konfigurationsanalyse (OpenAI/Azure OpenAI)
Configuration Drift /api/v1/configuration-drift Drift-Erkennung und Monitoring-Verwaltung
Workflows /api/v1/workflows Workflow-CRUD und Ausfuehrungsverwaltung
Diff /api/v1/diff Konfigurationsvergleich mit JSON/HTML-Export
Rollback /api/v1/rollback Rollbacks ausführen und Rollback-Historie verfolgen
Benachrichtigungen /api/v1/notifications Benachrichtigungskanal-Konfiguration und -Zustellung
Berichte /api/v1/reports Berichtsgenerierung und Security Assessments
Registry /api/v1/registry UTCM Resource Registry und Resource Type-Definitionen
CA What-If /api/v1/ca-whatif Conditional Access Policy-Simulation (Offline-Evaluation)
E-Mail-Sicherheit /api/v1/email-security DNS-basierte E-Mail-Sicherheitspruefungen (SPF, DKIM, DMARC)
Incidents /api/v1/incidents Incident Management mit NIS2-Meldefristen
Risikobewertung /api/v1/risk-assessment Risikobewertungen mit Scoring und Heat Map
Change Management /api/v1/change-management Change Requests und Approval Chain Workflows
Compliance /api/v1/compliance Compliance-Evaluation gegen Sicherheits-Frameworks
BC/DR /api/v1/bcdr Business Continuity / Disaster Recovery Testverwaltung
Audit-Nachweise /api/v1/audit-evidence Audit-Nachweis-Artefakt-Sammlung und -Verwaltung
Anomalie-Erkennung /api/v1/anomaly-detection ML-basierte Anomalie-Erkennung und Custom Monitoring Probes
Copilot Readiness /api/v1/copilot-readiness Microsoft 365 Copilot Readiness Assessment (44 Checks)
Gruppen /api/v1/groups Benutzergruppen-Verwaltung mit rollenbasiertem Zugriff
Einstellungen /api/v1/settings Systemweite Konfigurationseinstellungen
Setup /api/v1/setup System-Initialisierungsassistent (M365, Zscaler und Atlassian)
Admin /api/v1/admin Audit Logs, Systemgesundheit und Diagnose
Data Viewer /api/v1/data-viewer Datenbank-Tabellen-Viewer (nur Admin)
Health /health Health Check Endpoint (keine Authentifizierung erforderlich)

Diagnose-Endpoints

Endpoint Methode Zweck
/health GET Basis-Health-Check (Datenbankkonnektivitaet, Latenz)
/api/v1/diagnostics GET Vollständige Systemdiagnose (DB, Redis, Storage, Azure AD)
/api/v1/diagnostics/repair POST Automatische Reparatur (?action=create_storage_dirs oder ?action=run_migrations)

Strukturiertes Logging

Alle Requests erzeugen strukturierte Log-Einträge im Backend:

2026-03-05T14:30:00.000Z | INFO | SnapshotsController [req=abc123 op=createSnapshot user=admin@tcm.local] | Snapshot erstellt

X-Request-ID verwenden um Frontend-Requests, Backend-Logs und API-Responses über den gesamten Request-Lifecycle zu korrelieren.

Weiterfuehrende Dokumentation