Integrations-API

Restow liefert von Tag eins an in jeder Edition eine dokumentierte REST-API unter /api/v1, mit OpenAPI-Beschreibung: Sie ist keine kostenpflichtige Zusatzfunktion. Sie dient dazu, Restow an die Werkzeuge anzubinden, die ein MSP oder eine IT-Abteilung bereits einsetzt: RMM, PSA und Ticketsysteme. Wo die maschinenlesbare Beschreibung und die Betriebs-Endpunkte liegen, steht unter Referenz → API-Referenz.

Was sie abdeckt

• Sicherungs-, Restore- und Verify-Status sowie die zugrunde liegenden Jobs (mit einem Server-Sent-Events-Stream für Live-Fortschritt).
• Geschützte Objekte: Postfächer, OneDrives und IMAP-Konten, mit ihrem letzten Snapshot.
• Speicherziele und deren Zustand.
• Server und Clients, die der Agent sichert (GET /api/v1/endpoints), siehe Server und Clients.
• Archiv-Status und -Nachweise: Eingang je Erfassungsweg, Prüfung der Hash-Kette, Aufbewahrung und Legal Holds sowie ein Nachweisbericht für einen Zeitraum (siehe Archivierung).
• Die laufende Version und ob ein Update verfügbar ist, siehe Version und Updates.
• Eine Directory je Mandant: eine saubere Aufstellung von Nutzern und Postfächern, gedacht zur Weitergabe an ein PSA für Abrechnung oder Asset-Tracking.
• Webhooks (siehe unten).

API-Schlüssel und Berechtigungen

Legen Sie Schlüssel unter Integrationen → API-Schlüssel an. Jeder Schlüssel gehört zu einem Mandanten, hat einen Namen (sichtbar in der Schlüsselliste und im Audit-Log), einen optionalen Ablauf (30/90/180/365 Tage oder nie) und nur die Berechtigungen, die er braucht. Berechtigungen schließen einander nicht ein: Ein Schlüssel, der den Schutz ändert, braucht also zusätzlich Lesezugriff, wenn er auch Nutzer liest. Der vollständige Umfang:

Berechtigung	Gewährt
status:read	Zusammenfassung, Speicher, letzter Verify-Bericht, Server und Clients (Endpoints), laufende Version.
jobs:read	Jobs mit Fortschritt, Fehlern und Dauer.
items:read	Geschützte Objekte mit ihrem letzten Snapshot.
users:read	Die Nutzer-/Postfach-Directory, für PSA-Abgleich und Abrechnung.
archive:read	Archiv-Status, Erfassungswege, Kettenprüfung und der Nachweisbericht.
restore:write	Sicherungen und Wiederherstellungen starten.
verify:write	Verify-Läufe starten (stichprobenartige Test-Wiederherstellungen).
users:write	Nutzer ein- oder ausschließen, z. B. beim On- und Offboarding.
webhooks:manage	Webhooks dieses Mandanten anlegen, ändern und löschen.

Ein Schlüssel authentifiziert sich als Authorization: Bearer <Schlüssel> und ist auf 600 Anfragen je 10 Minuten begrenzt. Restow zeigt den Wert des Schlüssels einmal, bei der Erstellung. Gespeichert wird nur ein Fingerabdruck, ein verlorener Schlüssel lässt sich also nicht wiederherstellen, nur widerrufen und ersetzen. Der Widerruf ist sofort und unumkehrbar; der Eintrag bleibt für den Prüfpfad in der Liste.

Die Service-Provider-Edition bietet zusätzlich Provider-Schlüssel: Sie wirken über jeden vom Provider verwalteten Mandanten hinweg (Anfragen nennen den Mandanten mit einem X-Restow-Tenant-Header), für einen einzigen Integrationspunkt über alle Kunden hinweg.

Server und Clients

GET /api/v1/endpoints listet die Server und Clients auf, die der Restow-Agent sichert (Endpoint-Backup), für die Asset-Liste eines RMM oder die Abrechnung je Rechner. Der Aufruf braucht die Berechtigung status:read, nimmt optional profile=server oder profile=client entgegen und ist nicht seitenweise: Die Antwort ist { "items": [...], "total": n }. Jeder Lesezugriff wird wie die übrigen Lesezugriffe auditiert. Jeder Eintrag hat:

Feld	Bedeutung
id, hostname, displayName	Der Rechner.
profile	server oder client.
os, arch	Das System (heute linux oder darwin für macOS) und die CPU-Architektur (amd64 oder arm64).
agentVersion, status	Die Version des Agents sowie active oder revoked.
connection	online, wenn sich der Agent innerhalb von 15 Minuten gemeldet hat, sonst offline, oder never.
lastSeenAt, lastBackupAt, lastSuccessAt	Der letzte Kontakt, das Ende des letzten Sicherungslaufs unabhängig vom Ergebnis und das Ende der letzten Sicherung, die einen Snapshot erzeugt hat.
readiness	state (green, yellow, red, unverified oder no_backup), checkedAt und overdue. Ein Rechner ist erst green, wenn ein Restore-Test seiner neuesten Sicherung jeden Stichproben-Hash bestätigt hat.
attention	Warum der Rechner einen Blick braucht: silent, backup_overdue, last_backup_failed, restore_test_failed, repository_damaged oder never_seen.
createdAt	Wann der Rechner in Restow angelegt wurde.

GET /api/v1/status enthält außerdem ein Objekt endpoints mit den Zahlen total, servers, clients, revoked, needingAttention und lastSuccessAt.

Version und Updates

GET /api/v1/status meldet die laufende Version und den Opt-in-Update-Hinweis in einem Objekt version, damit ein RMM veraltete Installationen markieren kann. Seine Felder: running, latest (das neueste Release des Kanals, wenn die Prüfung lief), updateAvailable (null, wenn das nicht bekannt ist), releaseUrl, updateCheck (disabled, pending, ok oder failed), checkedAt, channel (stable oder beta), latestTag (wie veröffentlicht, zum Beispiel v1.2.3), publishedAt, checkError (warum die letzte Prüfung scheiterte, zum Beispiel rate_limited oder not_found; null, wenn sie nicht scheiterte) und maintenance (ein über den Updater angekündigtes oder laufendes Update, mit phase, targetVersion und startsAt; sonst null). Die Update-Prüfung ist aus, bis eine Administration sie einschaltet; auf einer frischen Installation ist updateCheck daher disabled. Ein Status-Aufruf wartet nie auf das Netzwerk. Siehe Updates.

Warum ein Job fehlgeschlagen ist

Job-Objekte tragen neben der einfachen errorMessage die Ursache eines Fehlers. failure enthält einen stabilen Ursachen-code (zum Beispiel graph.consent_missing, graph.throttled, imap.auth_failed, storage.full, verify.hash_mismatch oder unknown), seine category, ob Warten allein helfen kann (transient) oder ein manueller Neuversuch sinnvoll ist (retryable), params (die fehlende Berechtigung, den Host, die Wartezeit in Sekunden), geschwärzte technical-Details für einen Supportfall, occurredAt, den step, in dem der Lauf war, den automatischen retry-Zustand, die geordneten steps zur Behebung und eine docsUrl. Bei einem Job, der nicht fehlgeschlagen ist oder aus der Zeit vor der Ursachenerfassung stammt, ist er null. itemCauses nennt die Ursachen hinter den fehlgeschlagenen Elementen eines beendeten Jobs, die häufigste zuerst (höchstens drei). Das Job-Detail ergänzt jedes fehlgeschlagene Element um ein failure und liefert failureGroups, die fehlgeschlagenen Elemente nach Ursache gruppiert. Siehe Fehlererklärungen.

Webhooks

Restow ruft eine von Ihnen registrierte URL auf, wenn ein gewähltes Ereignis eintritt, zum Beispiel, damit ein PSA ein Ticket eröffnet, wenn eine Sicherung fehlschlägt. Derzeit definierte Ereignisse: job.failed, job.completed, verify.completed, dazu ein manuelles „Testereignis senden“. Jeder Webhook hat sein eigenes Signatur-Secret, einmal bei der Erstellung angezeigt (oder nach Secret erneuern): Jede Zustellung ist ein signierter JSON-POST, signiert als sha256=<HMAC-SHA-256 des rohen Bodys> im Header X-Restow-Signature, zusammen mit X-Restow-Event, X-Restow-Delivery und X-Restow-Attempt. Prüfen Sie die Signatur (zeitkonstanter Vergleich), bevor Sie einer Anfrage vertrauen. Eine Antwort ohne 2xx-Status wird nach 1 Min., 5 Min., 15 Min., 1 Std., 3 Std., 6 Std. und 12 Std. erneut versucht; HTTP 410 beendet die Zustellung sofort. Das Zustellprotokoll behält jeden Versuch etwa 30 Tage nach Abschluss, und eine Zustellung lässt sich auf Anfrage erneut senden.

Die Nutzlast von job.failed (data.job) trägt die Ursache als failure: den stabilen code, ob Warten allein helfen kann (transient) und die params, die ein Ticket braucht. Auch ein fehlgeschlagener Lauf eines Servers oder Clients löst job.failed aus, mit queue gleich endpoint_backup oder endpoint_restore und einem zusätzlichen data.endpoint (id, hostname, displayName, profile, os). Ein Lauf, den der Agent wegen eines Neustarts unterbrechen musste, ist kein Fehlschlag und löst keinen Webhook aus.

Webhook-Ziele in Loopback- oder privaten Netzen werden abgelehnt, sofern der Betreiber sie nicht erlaubt hat (RESTOW_WEBHOOK_ALLOW_PRIVATE); Link-Local (Cloud-Metadaten) und andere reservierte Bereiche werden unabhängig von dieser Einstellung immer abgelehnt.

Auditierung

Jeder Lesezugriff auf Nutzer- oder Sicherungsdaten über die API (durch einen Schlüssel oder durch die Web-Oberfläche) wird genauso ins Audit-Log geschrieben: wer (bzw. welcher Schlüssel), wann, was, für wen und von welcher IP.