Meduza Business API

Verwalten Sie Firmen, Mitglieder, VPN-Zugriff und Routen über dieselbe API, die auch der Firmenbereich nutzt.

Erste Version: 169 Methoden des aktuellen Vertrags — nicht 169 von 191 erfüllten Anforderungen. Der Entwurf nutzt andere Pfade und Abläufe. Vollständige Matrix der ersten Version: SSO/SCIM, Eigentümerwechsel, Firmware-Rollout auf Router, Konfigurationsexport und rechtliche Rechnungsangaben sind ausgenommen. notification-channels sind nur ein Legacy-Inventar: Ihr Vertrag und die Zustellung per email/webhook/in_app sind von der ersten Version ausgenommen. Sieben Alarmtypen sind in Monitoring, Audit und API verfügbar; die Zustellung über die separate signierte Webhooks-API bleibt im Umfang. Router und Ressourcen sind vorerst Inventar; billing-profile speichert nur Metadaten ohne Verbindung zu Rechnungen.

Autorisierung und Rechte

Basispfad: https://meduzacore.com/__api/api/business/v1. Die Oberfläche nutzt die aktuelle Benutzersitzung. Für Automatisierung legen Sie im Firmenbereich einen API-Client an und speichern das Secret bei der Ausgabe.

curl -X POST https://meduzacore.com/__api/api/business/v1/oauth/token \
  -d grant_type=client_credentials \
  -d client_id=YOUR_CLIENT_ID \
  -d client_secret=YOUR_SECRET

curl https://meduzacore.com/__api/api/business/v1/organizations/ORGANIZATION_ID/members \
  -H "Authorization: Bearer TOKEN"

Übergeben Sie das erhaltene Token in Authorization: Bearer TOKEN. Das Token gilt eine Stunde und nur innerhalb der Firma, die den Client ausgestellt hat. Der Zugriff wird entzogen, wenn der Client deaktiviert wird oder der Admin, der ihn angelegt hat, seine Rechte verliert.

Bezahlung und VPN-Bereitstellung

1. Legen Sie die Firma mit POST /organizations aus einer Benutzersitzung an.
2. Holen Sie über subscription/quotes ein Angebot ein: Anzahl der VPNs, Zeitraum und die Operation purchase, renewal oder upgrade.
3. Übergeben Sie quote_id und payment_method: stripe_card an subscription/checkout.
4. Die Antwort 202 bedeutet, dass die Rechnung vorbereitet wird. Lesen Sie invoices, bis payment_url erscheint, und bezahlen Sie über diesen Link.
5. Sobald das Zahlungsregister die Zahlung bestätigt, wird das Abo aktiv. Erstellen Sie VPNs mit einer pricing_id aus catalog/vpn-locations und dem Pflichtheader Idempotency-Key.

Ein Paket beginnt bei 5 VPNs. Grundpreis pro VPN: $5.99 im Monat oder $54.99 im Jahr. Paketrabatt: 5–9 VPNs — 5 %, 10–99 — 10 %, ab 100 — 20 %. Die Rückkehr in den Browser nach der Zahlung schaltet den Zugang erst nach Prüfung der Zahlung frei.

Eine Verlängerung behält Anzahl und Zeitraum bei. Bei einer Vergrößerung des Pakets wird die Differenz für die Restlaufzeit berechnet. Um einen Server endgültig zu entfernen, verwenden Sie POST /organizations/{organization_id}/vpns/{id}/retire mit confirm: true und If-Match. Der Platz wird nach bestätigter Entfernung frei, der Abopreis ändert sich nicht. Die Zuweisung an Mitarbeitende wird als member_id übergeben; ohne sie steht das VPN der Firma gemäß den Zugriffszuweisungen zur Verfügung.

Wer ein Firmen-VPN nutzen darf, legt das Feld access in PATCH /organizations/{organization_id}/vpns/{id} mit If-Match fest. company öffnet es allen Mitgliedern der Firma, deren Rolle Verbindungen erlaubt; die Listen member_ids und group_ids werden geleert. restricted beschränkt es auf die aufgeführten Mitarbeitenden und die Mitglieder der aufgeführten Gruppen; leere Listen entziehen allen den Zugriff. company zusammen mit nicht leeren Listen wird mit 422 abgelehnt. GET-Antworten und /me/vpn-grants enthalten immer data.access, auch für VPNs, die vor Einführung des Feldes angelegt wurden. Eine Anfrage ohne access, aber mit member_ids oder group_ids stellt das VPN wie bisher auf restricted. Ein dediziertes VPN eines Mitarbeitenden ist immer restricted. Moduswechsel werden im Audit als vpn_access_changed protokolliert; wird der Zugriff eingeschränkt, werden die Schlüssel der Geräte ohne Zugriff widerrufen.

curl -X PATCH https://meduzacore.com/__api/api/business/v1/organizations/ORGANIZATION_ID/vpns/VPN_ID \
  -H "Authorization: Bearer TOKEN" \
  -H 'If-Match: "3"' \
  -H "Idempotency-Key: vpn-access-1" \
  -H "Content-Type: application/json" \
  -d '{"access":"company"}'

Routen und Verkehrssätze

Ein Satz beschreibt Websites oder Netze, eine Regel wählt die Aktion: ein bestimmtes VPN, direkt oder gesperrt. Verwenden Sie Länder und Regionen aus catalog/traffic-presets. Im Modus first-match werden die Regeln von oben nach unten geprüft, höchstens 128; für „Restlichen Verkehr“ ist Sperren nicht verfügbar.

Speichern erzeugt einen Entwurf. Führen Sie die Prüfung aus und veröffentlichen Sie dann mit If-Match. Prüfen Sie policy-deployments: In der Warteschlange und vom Gerät bestätigt angewendet sind verschiedene Zustände. Die Verbindung zum VPN stellt die Client-App her.

Rollen, Gruppen und Geräte

GET /organizations/{id}/roles liefert integrierte und eigene Rollen, Rechtedefinitionen und das Merkmal can_manage. Der Inhaber erstellt eine eigene Rolle auf Basis von Admin, Mitarbeitendem oder Finanzrolle und behält nur die nötigen Rechte. Zuweisung über PATCH members/{id}: role und custom_role_id. Rechteänderungen gelten auch für die API-Clients des Benutzers, der sie angelegt hat.

Eine Rolle erlaubt Aktionen im Firmenbereich. group_ids weist Mitarbeitenden VPNs und ein Routing-Paket zu; die Mitgliedschaft in einer Gruppe gibt keine Admin-Rechte. Die Inhaberrolle lässt sich nicht in eine eigene Rolle kopieren. Eine Mitarbeitenden zugewiesene Rolle kann nicht gelöscht werden.

Geräte erhalten einen display_name, einen Besitzer und VPN-Angaben. PATCH devices/{id} ändert nur den Namen, geprüft per If-Match. POST devices/{id}/revocations beantragt die Sperre; den endgültigen Status bestätigt der Knoten. Eigene Geräte sind über /me/devices verfügbar. Das Feld last_api_ip ist die Transportadresse der API, nicht die der VPN-Verbindung. Name und Modell, die die App meldet, werden nicht zur Autorisierung verwendet.

Verbindungen und Zielprotokoll

GET /organizations/{id}/employee-analytics zeigt beobachtete Verbindungen, Zustandswechsel und den stündlichen Verlauf über 7 Tage. Eine fehlende Messung wird nicht durch null ersetzt; die Anzahl der Sitzungen ist nicht die Arbeitszeit der Mitarbeitenden.

GET /organizations/{id}/activity liefert die vom Knoten erfassten Verbindungsanfragen: angefragte Domain oder IP, Port, Protokoll, Zeit, Entscheidung, Gerät und Mitarbeitende. Filter: from, to, member_id, action, search; Seiten über cursor und limit. Die Domain hat der Client in der Verbindungsanfrage übermittelt; sie stammt nicht aus entschlüsseltem HTTPS.

Die Erfassung ist standardmäßig aus. Der Inhaber ändert activity-settings per PATCH mit {"enabled": true} und If-Match. Lesen erfordert activity.read. Bei aktiver Erfassung zeigt die App den Mitarbeitenden einen Hinweis; die Schlüsselausgabe erfordert nach Prüfung des Schlüsselinhabers eine aktuelle Bestätigung X-Corporate-Activity-Version. Ein alter Client erhält für diesen Modus keinen Schlüssel.

Die Speicherung ist auf 7 Tage und 100.000 Ereignisse pro Firma begrenzt; der Puffer des Knotens hält bis zu 24 Stunden. coverage meldet Aktualität, nicht erreichbare Geräte und Pufferverluste. Private VPNs, direkter Geräteverkehr, lokale Sperren vor Erreichen des Knotens, HTTPS-Pfade, Inhalte von Anfragen und Produktivitätsbewertungen werden nicht erfasst. Das Abschalten der Erfassung stellt fehlenden Verlauf nicht wieder her und löscht bereits erfasste Einträge nicht sofort: Es gilt die Aufbewahrungsfrist.

Kategorien und Zeit der Netzwerkaktivität

Die Antwort des Protokolls enthält analysis: Verteilung nach Kategorien, Mitarbeitenden und Stunden, die wichtigsten Ziele und die Anzahl active_minutes. Die Zusammenfassungen werden über alle gespeicherten Ereignisse des gewählten Zeitraums berechnet, unabhängig von der Seite des Rohprotokolls. Mit dem Filter category gelangen Sie zu den konkreten Ereignissen.

Eine aktive Minute ist eine eindeutige Minute einer Person, in der der Knoten eine Anfrage beobachtet hat. Das ist nicht die Dauer des Besuchs einer Website oder der Arbeit: Hintergrundverkehr zählt mit, und Kategorien können sich innerhalb einer Minute überschneiden. Die Gesamtzeit wird separat berechnet und ist nicht die Summe der Kategorien.

Der Inhaber legt in den Protokolleinstellungen bis zu 64 Regeln classification_rules fest: Domain und Kategorie. Sie gelten auch für Subdomains und haben Vorrang vor dem integrierten Verzeichnis. Unbekannte Ziele bleiben eine eigene Kategorie. Die aktuellen Regeln klassifizieren den gesamten gewählten Zeitraum; die Antwort nennt die Version der Klassifizierung.

Verarbeitet werden die Ziele der Firmenverbindungen, nicht HTTPS-Inhalte, vollständige URLs oder privater Verkehr. Die Bestätigung des Hinweises wird einmal pro Person und Firma gespeichert; das Ändern von Kategorien, Gruppen oder des Erfassungsmodus erfordert keine erneute Bestätigung desselben Hinweises. Hinweise auf unvollständige Abdeckung und truncated dürfen nicht als fehlende Aktivität gedeutet werden.

Ereignisabonnements

Legen Sie webhooks mit einer öffentlichen HTTPS-URL auf Port 443 und den Ereignissen audit.event, * oder groups.created, members.updated und weiteren Ressourcenänderungen an. Das Secret wird nur beim Erstellen oder Rotieren angezeigt.

Meduza-Signature: t=UNIX_SECONDS,v1=HEX_SIGNATURE
Meduza-Event-Id: EVENT_ID
Meduza-Delivery-Id: DELIVERY_ID

HEX_SIGNATURE = HMAC-SHA256(secret, timestamp + "." + RAW_JSON_BODY)

Prüfen Sie die Signatur anhand der Rohbytes des Bodys, das zulässige Alter des Timestamps und wiederholte Event-IDs. Behalten Sie während der Rotation das vorherige Secret für bereits eingereihte Ereignisse. Jede 2xx-Antwort gilt als Erfolg; andere Antworten werden mit wachsendem Abstand wiederholt, bis zu acht Versuche. Verlauf und manuelle Neuzustellung sind über deliveries verfügbar. Erfolgreiche und abgebrochene Zustellungen werden bis zu 30 Tage gespeichert, höchstens 2.000 pro Webhook. Warteschlange und Fehler sind auf 1.000 Ereignisse begrenzt; bei Überlauf werden die ältesten Ereignisse verworfen, der Zähler dropped_deliveries meldet den Verlust. Gleichen Sie in diesem Fall den Zustand über die API ab.

Die Zustellung erfolgt mindestens einmal. Neben Änderungen über die API werden bestätigte Änderungen an Rechnungen (invoices.updated), Abos (subscriptions.updated), der VPN-Bereitschaft (vpns.updated) und Alarme (alerts.created) gesendet. Erneutes Abfragen ohne Zustandsänderung erzeugt kein neues Ereignis. Dies ist kein Strom des Netzwerkverkehrs. Private IPs, Weiterleitungen und Aufrufe interner Dienste sind verboten.

API-Methoden

Vertrag wird geladen…

Seiten und Filter von Listen

Übergeben Sie für Inventarlisten limit=1..200 und danach cursor aus next_cursor, die übrigen Parameter unverändert. Ohne limit/cursor erhalten ältere Clients die vollständige Liste: Daten werden nie stillschweigend abgeschnitten. Verfügbar sind status, member_id, user_id, vpn_id, search und created_from/created_to (RFC3339, Untergrenze eingeschlossen, Obergrenze ausgeschlossen). Der Zugriff wird vor dem Filtern und auf jeder Seite geprüft. Unbekannte oder doppelte Parameter ergeben 422. Listen des Aktivitätsprotokolls nutzen einen eigenen Vertrag. Parameter jeder Methode.

Was diese Version berücksichtigt

Das administrative Audit wird bis zu 90 Tage gespeichert, höchstens die letzten 10.000 Ereignisse pro Firma; abgelaufene Idempotenz-Einträge werden bereinigt. Rechnungen und Abos löscht diese Bereinigung nicht. Inventarlisten liefern items, total und next_cursor; eine Fortsetzung gibt es bei explizitem limit/cursor. Ohne sie bleibt die vollständige Antwort mit älteren Clients kompatibel. Das Protokoll activity unterstützt separat einen Cursor und die dokumentierten Filter. Secrets werden in Antworten aus dem Idempotenz-Cache nicht wiederholt. Die bestätigte Schlüsselsperre kommt vom VPN-Server; das Deaktivieren einer Mitgliedschaft verhindert sofort neue Ausgaben.

Das Monitoring zeigt tatsächliche Verbindungen und Last. Der Zielverlauf ist über ein separates, ausdrücklich einzuschaltendes Protokoll verfügbar. HTTPS-Inhalte und Produktivitätsbewertungen der Mitarbeitenden gehören nicht zu diesen Daten. SSO/SCIM und weitere Methoden aus dem erweiterten Entwurf sind nicht Teil dieses implementierten Vertrags.

Verwaltungsfehler liefern application/problem+json mit status, detail und request_id. Fehler bei der Ausgabe von OAuth-Tokens verwenden das Feld error.