API-Übersicht

Die Eviworx REST API ermöglicht programmatischen Zugriff auf alle Plattform-Features. Die API ist vollständig RESTful, verwendet JSON für Request/Response-Bodies und wird über Traefik als API-Gateway bereitgestellt.

Base URL

https://your-eviworx-instance.com/api

Alle API-Requests laufen über Traefik (Port 443), das die Requests an das Backend (Port 3000) weiterleitet.

Authentifizierung

Jeder Request wird entweder einem Benutzer oder einem API-Key zugeordnet. Für beide gelten dieselben rollenbasierten Berechtigungen:

Actor	Mechanismus	Verwendung
User	JWT als HttpOnly-Cookie (Session)	Frontend/Portal; Token NICHT im Body, MFA/TOTP optional
API-Key	X-API-Key Header	Externe Integrationen. Ein Key ohne Rolle hat keine Berechtigungen. Der Key wird nur im Header X-API-Key akzeptiert, nicht als Authorization: Bearer.

Die meisten Endpoints akzeptieren beide Wege. Einige sind nur für angemeldete Benutzer freigegeben und antworten einem API-Key mit 403, z. B. Reports, Formulare, Linking-Listen und Textbausteine. Berechtigungen werden pro Rolle ermittelt; Änderungen an einer Rolle wirken sofort. Details: Authentication · RBAC.

Enum-Konvention (wichtig)

Enum-Werte werden in Requests und Responses in Großbuchstaben geschrieben. Kleingeschriebene Werte lehnt der Server mit 400 ab. Beispiel Ticket-Priorität: "HIGH".

// POST /api/tickets
{ "priority": "HIGH" }
// Response:
{ "priority": "HIGH", "status": "OPEN" }
// "priority": "high" → 400

Gilt analog für visibility/status (Knowledge Base), category-Enums (Forms), impact/urgency (Incidents), changeType (Changes) usw. Mehrwertige Felder (z.B. tags) sind frei. Die jeweils gültigen Werte stehen auf den Domain-Seiten, ebenso einzelne kleingeschriebene Wertemengen wie die CronJob-Action-Types.

Verfügbare Endpoints

ITSM Core

Modul	Endpoint	Beschreibung
Tickets	/api/tickets	CRUD, Kategorien, Participants (Follower/CC), E-Mail-Actions
Incidents	/api/incidents	CRUD, DSGVO-Flow, Evidence-Checklisten, Kategorien
Problems	/api/problems	CRUD, Kategorien, Root-Cause-Analyse
Changes	/api/changes	CRUD, Approvals, Templates, Kategorien, BACKED_OUT-Status
Approvals	/api/approvals	Unified Approvals API (Changes, Incidents u.a.)
Linking	/api/linking	Entity-Verknüpfungen (Ticket↔Problem, Asset↔Contract etc.)

Asset Management

Modul	Endpoint	Beschreibung
Assets	/api/assets	CRUD, Checkout/Checkin, QR-Scan
Asset Types	/api/asset-types	AssetType-Verwaltung inkl. Policies
Asset Categories	/api/asset-categories	Kategorien-Verwaltung
Asset Locations	/api/asset-locations	Standort-Verwaltung
Asset Relations	/api/asset-relations	CMDB-Beziehungen zwischen Assets
Model Clusters	/api/asset-model-clusters	Model-Deduplizierung & Clustering
Handover	/api/handovers	QR/PDF-basierte Asset-Übergabe
Inventory	/api/inventory-sessions	Inventur-Sessions mit Workflow-Integration

Automation & Workflows

Modul	Endpoint	Beschreibung
Workflows	/api/workflow	Templates, Instanzen, Tasks, Publishing, Versioning
CronJobs	/api/cronjobs	Geplante Jobs, Konfiguration, Ausführungen, 28 Action-Types
SLA	/api/sla	SLA-Policies, Business Hours, Holidays, Eskalation

Benutzer & Sicherheit

Modul	Endpoint	Beschreibung
Auth	/api/auth	Login, Logout, Refresh, 2FA/TOTP, Forgot/Reset Password
Users	/api/users	Benutzerverwaltung, Einladungsemail, Notification-Preferences
Roles	/api/roles	Rollen-Verwaltung mit Berechtigungen
Agents	/api/agents	Agent-Profile, Groups, Specialties, Kapazität
Absences	/api/absences	Abwesenheits-Management (Substitute, Verfügbarkeits-Filter bei Zuweisung)
Entra ID	/api/entra-id	SSO, OAuth-Callback, Sync, Config
API Keys	/api/api-keys	API-Key-Verwaltung für externe Integrationen
Audit	/api/audit	Audit-Logs, Enterprise Audit, Chain-Verification

Kommunikation & E-Mail

Modul	Endpoint	Beschreibung
Notifications	/api/web-notifications	In-App-Notifications, Web-Push
Notification Templates	/api/notification-templates/v2	Mehrsprachige Notification-Templates
Mailboxes	/api/inbound-mailboxes	Individuelle Mailbox-Konfiguration (IMAP/Graph API)
Email Signatures	/api/email-signatures	E-Mail-Signaturen pro Mailbox
Response Templates	/api/response-templates	Textbausteine für den Ticket-Composer (Scope PERSONAL/AGENT_GROUP/ORGANIZATION)
Teams Bot	/api/teams/bot	Microsoft Teams Bot Framework Endpoint

Wissensmanagement & Dokumente

Modul	Endpoint	Beschreibung
Knowledge Base	/api/knowledge-base	Wissensdatenbank-Artikel
eLibrary	/api/elibrary	Dokumenten-Bibliothek
Attachments	/api/attachments	Dateianhänge für alle Objektarten, Virenscan-Status
Contracts	/api/contracts	Vertragsverwaltung, Asset-Linking
Licenses	/api/licenses	Lizenzverwaltung, Seat-Management, Publisher/Products

Dashboards & Reports

Modul	Endpoint	Beschreibung
Dashboard	/api/dashboard	Unified Workplace, NOC-Dashboard, Widgets
Analytics	/api/analytics	Interaktive Analytics-Auswertungen
Reports	/api/reports	Standard-Reports
Custom Reports	/api/custom-reports	Benutzerdefinierte Reports, CSV/PDF-Export

System & Konfiguration

Modul	Endpoint	Beschreibung
Settings	/api/settings	System-Einstellungen, E-Mail, Teams, Notifications, System-Status
File Settings	/api/settings/file-settings	Datei-Upload-Konfiguration
Search	/api/search	Globale Suche über neun Entitätstypen — eigene Seite
Saved Views	/api/saved-views	Gespeicherte Listen-Zuschnitte für elf Entitäten — eigene Seite
Forms	/api/forms	Dynamische Formulare (rollenbasiert)
Health	/api/health	Basis-Check und Probes (live, ready) sowie der System-Status aller Dienste
Telemetry	/api/telemetry/client-error-batch	Fehlerberichte aus dem Browser (POST, Anmeldung optional, rate-limitiert)

My-Tasks (Cross-Domain-Aggregator)

/api/my-tasks liefert die offenen Arbeits-Items des angemeldeten Benutzers aus allen Bereichen in einer Liste. Enthaltene Typen (MyTaskType): TICKET, INCIDENT, PROBLEM, CHANGE, CHANGE_TASK, WORKFLOW_STEP. Genehmigungen liefert /api/approvals.

Method	Endpoint	Beschreibung
GET	/api/my-tasks?scope=…&types=…&search=…&limit=…&offset=…	Arbeits-Items eines Scopes (Default own), Antwort { data, pagination }. types = Komma-Liste, search = Titel/Nummer (max. 200 Zeichen), limit 1–200 (Default 50), offset ab 0. Ungültige Werte werden mit 400 abgelehnt. Zähler liefert /api/my-tasks/count.
GET	/api/my-tasks/count?tz=…	Zähler ALLER drei Scopes in einer Antwort: { total, byType, own, group, substitute }, je mit total, byType, overdue und dueToday. Einziger Parameter ist tz (IANA-Zone für die Tagesgrenze von dueToday; ohne Angabe gilt die Systemzone).

scope	Menge
own	mir zugewiesen (Default)
group	Vorgänge meiner Gruppen OHNE Bearbeiter — der Vorrat, den ich ziehen kann
substitute	Vorgänge eines Bearbeiters, den ich gerade vertrete

Die drei Mengen sind DISJUNKT: ein Vorgang liegt in genau einem Scope. Ein Gruppen-Vorgang, den bereits ein Kollege bearbeitet, ist damit weder „meine Aufgabe" noch Vorrat. Tickets, Incidents und Probleme tragen ihr dueDate aus dem SLA-Tracking (Reaktionsfrist vor Lösungsfrist); ein pausiertes Tracking trägt slaState: PAUSED, kein dueDate und zählt nie als überfällig.

Das Dashboard (Unified Workplace) nutzt diesen Endpoint; die Workflow- und Approvals-Seiten verweisen darauf (z. B. WORKFLOW_STEP-Tasks).

Erste Schritte

1. Login (Token als HttpOnly Cookie)

curl -X POST https://your-instance.com/api/auth/login \
  -H "Content-Type: application/json" \
  -c cookies.txt \
  -d '{
    "email": "admin@company.com",
    "password": "your-password"
  }'

Response (Token wird als HttpOnly Cookie gesetzt, NICHT im Body):

{
  "user": {
    "id": "admin-user-001",
    "email": "admin@company.com",
    "name": "Admin User"
  },
  "expiresAt": "2026-03-17T13:00:00.000Z"
}

Bei aktivierter MFA/TOTP wird stattdessen eine 2FA-Challenge zurückgegeben:

{
  "requiresTwoFactor": true,
  "twoFactorEnabled": true,
  "twoFactorPendingToken": "pending-token...",
  "expiresAt": "2026-03-17T12:05:00.000Z",
  "user": { "id": "...", "email": "admin@company.com" }
}

2. API Request (Cookie wird automatisch mitgesendet)

# With curl and a saved cookie:
curl -X GET https://your-instance.com/api/tickets \
  -b cookies.txt \
  -H "Content-Type: application/json"

# Or with an API key (for external integrations):
curl -X GET https://your-instance.com/api/tickets \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json"

HTTP-Statuscodes

Code	Bedeutung
200	Success
201	Created
400	Bad Request — ungültige Eingaben (errorCode VALIDATION_ERROR)
401	Unauthorized
403	Forbidden (fehlende Berechtigung, errorCode FORBIDDEN; required nennt das geforderte Recht, siehe Fehlerbehandlung)
404	Not Found (Objekt nicht gefunden, errorCode NOT_FOUND)
409	Conflict (gleichzeitige Änderung oder Dublette, errorCode DUPLICATE_ENTRY)
429	Too Many Requests (Rate Limit)
500	Internal Server Error (nur allgemeine Fehlermeldung)

Fehlerbehandlung

Fehler werden im folgenden Format zurückgegeben:

{
  "error": "Validation failed",
  "errorCode": "VALIDATION_ERROR",
  "details": []
}

Felder: error (Meldung), errorCode (Code, z.B. VALIDATION_ERROR / DUPLICATE_ENTRY / NOT_FOUND / FORBIDDEN), optional details. 500-Antworten enthalten nur eine allgemeine Fehlermeldung.

403 bei fehlendem Recht

Jede Ablehnung durch die Rechteprüfung trägt errorCode FORBIDDEN und nennt im Feld required das geforderte Recht. Bei einem einfachen Recht ist required ein String:

{
  "error": "Insufficient permissions",
  "errorCode": "FORBIDDEN",
  "required": "tickets.viewAll",
  "source": "redis"
}

Bei kritischen Aktionen ist required ein Array; missing nennt das fehlende Recht:

{
  "error": "Insufficient permissions",
  "errorCode": "FORBIDDEN",
  "required": ["tickets.delete"],
  "missing": ["tickets.delete"],
  "source": "database"
}

Genügt für eine Route eines von mehreren Rechten, listet required alle Rechte, die Zugang gewähren würden:

{
  "error": "Insufficient permissions",
  "errorCode": "FORBIDDEN",
  "required": ["tickets.viewAll", "tickets.viewOwn"],
  "source": "redis"
}

Clients sollten required deshalb als String oder Array auswerten. source dient nur der Diagnose und zeigt, woher die geprüften Rechte stammen (redis = Rollen-Cache, database = frisch aus der Datenbank). Hat der Aufrufer keine aktive Rolle, lautet die Antwort error "No active role assigned" mit errorCode FORBIDDEN und detail "Please contact administrator", ohne required. Fachliche Ablehnungen einzelner Bereiche tragen eigene 403-Codes (z. B. ABSENCE_VIEW_FORBIDDEN); sie stehen auf der jeweiligen API-Seite.

Rate Limiting

Rate-Limiting ist zweistufig implementiert:

Ebene	Limit	Details
Traefik (Gateway)	100 req/s, Burst 200	Global für alle API-Requests
Backend (Auth)	Eingeschränkt	Login, Refresh, 2FA, Password-Reset
Backend (File Upload)	200/Stunde/IP	Datei-Uploads
Backend (E-Mail)	60/min	E-Mail-Versand
Backend (Critical Ops)	Eingeschränkt	Admin-Operationen, CronJob-Execution

Pagination

Die meisten Listen-Endpoints verwenden dieselben Query-Parameter: page und per (Seitengröße mit Obergrenze je Endpoint, z. B. Tickets max. 200/Standard 50, KB max. 100/Standard 20) sowie optional cursor. Filter, Suche und Sortierung folgen der FilterSpec der jeweiligen Entität.

# page-based:
GET /api/tickets?page=1&per=50

# cursor-based (large/live lists):
GET /api/tickets?cursor=clx-next&per=50

Es gibt zwei Response-Shapes (je nach Endpoint):

// cursor-based (e.g. tickets):
{ "data": [ /* ... */ ], "cursor": "clx-next", "hasMore": true, "pagination": { "total": 420, "limit": 50 } }

// page-based (e.g. knowledge base):
{ "data": [ /* ... */ ], "pagination": { "page": 1, "limit": 20, "total": 42, "totalPages": 3, "hasMore": true } }