Die empowsec Entwickler-Doku: Ihr Portal zur API-Integration

Die meisten Integrationsprojekte scheitern nicht am Code - sie bleiben in einer Support-Warteschlange stecken. Ein Entwickler möchte wissen, welcher Endpunkt Benutzer auflistet, welchen Scope ein Schlüssel braucht oder was eine 429-Antwort bedeutet - und statt die Antwort zu lesen, öffnet er ein Ticket und wartet. empowsec liefert seine Entwicklerdokumentation als Portal direkt im Produkt unter /docs aus, sodass die Antwort auf fast jede Integrationsfrage nur ein Lesezeichen entfernt ist - für Reseller und Unternehmen gleichermaßen.

Was die empowsec API und die Webhooks konkret können, haben wir in einem früheren Deep Dive behandelt. In diesem Artikel geht es um das Dokumentationserlebnis selbst: wie das Portal aufgebaut ist, was jeder Abschnitt abdeckt, warum das Changelog einen festen Platz in der Routine Ihres Teams verdient und wie ein einziger rollenbasierter Link jeden Admin ohne Menüsuche zu seinem API-Schlüssel bringt.

Ein Dokumentationsportal direkt im Produkt

Das Portal lebt unter /docs auf Ihrer empowsec-Instanz und ist ohne Login lesbar - ein Entwickler kann die Integrationsoberfläche bewerten, bevor überhaupt ein Konto existiert. Es gibt kein PDF, das versioniert werden müsste, und kein externes Wiki, das veraltet; die Doku wird mit dem Produkt ausgeliefert und ist wie der Rest der Plattform lokalisiert, sodass Ihr Team sie in derselben Sprache liest wie die Anwendung selbst.

Die linke Navigation ist in drei Abschnitte gegliedert, die widerspiegeln, wie Teams tatsächlich integrieren. Der Abschnitt Reseller API richtet sich an MSPs und Partner, die ein Kundenportfolio automatisieren. Der Abschnitt Company API richtet sich an interne IT- und Security-Teams, die eine einzelne Organisation anbinden. Und der Abschnitt Ressourcen sammelt alles, was beide Zielgruppen teilen: Webhooks, Fehlerbehandlung und das Changelog. Ganz gleich, welche Rolle Sie haben - der Weg von der Frage zur Antwort folgt derselben Form: Abschnitt wählen, die Guides der Reihe nach lesen, dann die Referenzseiten beim Bauen offen halten.

Der Reseller-API-Abschnitt: ein Kundenportfolio automatisieren

Der Reseller-Pfad beginnt mit einem Überblick und einem Erste-Schritte-Guide, dann einer Authentifizierungsseite, bevor er sich in vier Referenzbereiche auffächert: Unternehmen, Sitze, Benutzer und Berichte. Zusammen bilden sie exakt die Vorgänge ab, die ein MSP jede Woche durchführt. Die Unternehmens-Referenz behandelt die Verwaltung der Kundenorganisationen, die Sie betreuen. Die Sitze-Referenz dokumentiert das Auslesen Ihrer Pool-Übersicht und das Anpassen der Sitzzuteilung eines Kunden - das programmatische Gegenstück zum Seat-Pool-Workflow im Reseller-Portal. Die Benutzer-Referenz deckt die Verwaltung von Personen über Kundenunternehmen hinweg ab, und die Berichte-Referenz ist die Quelle für kundenübergreifende Nutzungsdaten.

Weil die Referenzseiten Methoden, Pfade und erforderliche Scopes ausweisen, sieht ein Integrator auf einen Blick, dass das Lesen von Sitzdaten und das Schreiben von Sitzzuteilungen getrennt berechtigte Operationen sind - und kann Zugangsdaten entsprechend ausstellen. Das ist der Unterschied zwischen einer Dokumentation, die eine API beschreibt, und einer, die den sicheren Umgang mit ihr lehrt.

Der Company-API-Abschnitt: eine Organisation anbinden

Der Unternehmens-Pfad folgt demselben Rhythmus - Überblick, Erste Schritte, Authentifizierung - und verengt sich dann auf die drei Dinge, die ein internes Team am häufigsten anbindet: Benutzer, Training und Phishing. Die Benutzer-Seiten behandeln die programmatische Benutzerverwaltung - das Fundament, um empowsec mit Ihrem HR-System of Record synchron zu halten. Die Training-Seiten dokumentieren, wie sich Daten aus dem Security-Awareness-Training abrufen lassen, damit Abschlussstände ohne manuelle Exporte in Compliance-Dashboards fließen. Die Phishing-Seiten decken die Daten der Phishing-Simulationen ab, sodass Security-Teams Simulationsergebnisse in dieselbe Reporting-Pipeline einspeisen können wie ihre übrigen Risikosignale.

Die Trennung von Unternehmens- und Reseller-Pfad ist eine bewusste Entscheidung. Ein Unternehmens-Integrator muss nie um Portfolio-Konzepte herumlesen, die ihn nicht betreffen, und ein MSP-Entwickler muss nie raten, welche Endpunkte kundenübergreifend arbeiten und welche innerhalb eines Kunden. Jede Zielgruppe erhält einen linearen Weg: drei Guide-Seiten lesen, dann gegen die Referenzen bauen, die zum eigenen Anwendungsfall passen.

Ressourcen: Webhooks, Fehler und das Changelog als Upgrade-Radar

Der Ressourcen-Abschnitt ist gemeinsame Infrastruktur für beide Zielgruppen. Die Webhooks-Seite dokumentiert die Push-Seite von empowsec - wie Ereignis-Nutzlasten Ihren Endpunkt erreichen, damit Integrationen auf Geschehnisse reagieren, statt danach zu pollen. Die Fehler-Seite katalogisiert Antwortcodes und ihre Bedeutung - das macht aus einer fehlschlagenden Integration eine Diagnose statt eines Rätsels: Ist es ein Authentifizierungsproblem, eine fehlerhafte Anfrage oder etwas auf der Serverseite? Fehlerbehandlung gegen einen dokumentierten Katalog zu bauen ist deutlich robuster, als aus einem einzelnen beobachteten Fehler zu raten.

Das Changelog verdient besondere Aufmerksamkeit als Arbeitsgewohnheit, nicht nur als Seite. Jede dokumentierte Änderung an der API landet dort - das macht es zu Ihrem Upgrade-Radar: Ein regelmäßiger Blick zeigt, wann neue Fähigkeiten erscheinen, die eine bestehende Integration vereinfachen könnten, und wann anstehende Änderungen vor dem nächsten Deployment einen genaueren Blick verdienen. Teams, die das Changelog planmäßig prüfen, werden vom Verhalten ihrer Integration nie überrascht; Teams, die es nicht tun, erfahren von Änderungen stattdessen aus ihrem Monitoring.

Ein Link zu Ihrem API-Schlüssel - unabhängig von der Rolle

Dokumentation tut sich traditionell mit einer Anweisung schwer: 'Holen Sie sich jetzt Ihren API-Schlüssel'. Die richtige Schlüssel-Seite unterscheidet sich je nach Zielgruppe - also beschreibt eine Doku entweder jeden Weg und verwirrt alle, oder einen Weg und lässt den Rest stranden. empowsec löst das mit einem rollenbasierten Deep Link: /docs/get-api-key. Ein angemeldeter Reseller Admin, der ihm folgt, landet direkt auf der Verwaltungsseite für Reseller-API-Schlüssel. Ein Company Admin landet in den API-Einstellungen des Unternehmens. Wer nicht angemeldet ist, wird zuerst zur Login-Seite geschickt, und ein angemeldeter Benutzer, dessen Rolle keinen API-Zugang hat, kehrt mit einem klaren Hinweis zur Doku zurück, dass API-Schlüssel von Admins verwaltet werden.

Es ist eine kleine Funktion mit großer Wirkung: Jedes Tutorial, jede Onboarding-E-Mail und jedes interne Runbook kann einen einzigen universellen Link enthalten, und jeder Leser landet exakt dort, wo seine Rolle es erlaubt. Keine Screenshots von Menüs, die je nach Rolle anders aussehen, und keine Support-Tickets, die mit 'Wo finde ich meinen Schlüssel?' beginnen.

Das Wichtigste in Kürze

• Das Doku-Portal lebt im Produkt unter /docs: keine PDFs, kein veraltetes Wiki, lokalisiert wie die restliche Plattform und ohne Login lesbar.
• Drei Abschnitte spiegeln reale Integrationspfade: Reseller API (Unternehmen, Sitze, Benutzer, Berichte), Company API (Benutzer, Training, Phishing) und geteilte Ressourcen.
• Die Guides folgen einer Reihenfolge - Überblick, Erste Schritte, Authentifizierung - sodass neue Integratoren einen linearen Weg von null zur ersten Anfrage haben.
• Die Fehler-Seite macht aus Ausfällen Diagnosen, und die Webhooks-Seite dokumentiert die Push-Seite der Plattform.
• Das Changelog ist Ihr Upgrade-Radar: Prüfen Sie es planmäßig, um neue Fähigkeiten zu entdecken und Änderungen zu bewerten, bevor sie Ihre Integration erreichen.
• /docs/get-api-key ist rollenbasiert: Reseller Admins, Company Admins, Besucher und Benutzer ohne Admin-Rechte landen jeweils genau dort, wo sie hingehören.