Einführung
Wozu dient die SoSafe-API?
Mit der SoSafe-API (Programmierschnittstelle) können Kunden und Partner wie Sie direkt über Software auf wichtige Informationen zu ihren Cybersicherheitsmaßnahmen mit SoSafe zugreifen, ohne sich im Manager anmelden und die Daten dort manuell ansehen oder herunterladen zu müssen. Mit der API können Sie unter anderem diese Informationen automatisch abrufen:
- Informationen zu Mitarbeitenden: Wer nimmt an Ihren SoSafe-Awarenessmaßnahmen teil?
- Schulungsfortschritt: Wie weit sind Ihre Mitarbeitenden mit den Schulungen bisher gekommen?
- Abgeschlossene Lektionen: Wer hat seine Lektionen bereits abgeschlossen und wer hat noch welche vor sich?
- Team-Engagement: Welche Gruppen sind bereits weiter als andere und welche hängen zurück?
- Risiko-Level & sicheres Verhalten: Wie gut sind die Mitarbeitenden darin, simulierte Phishing-Mails zu erkennen, und wie oft werden diese gemeldet?
Sie können diese Informationen nutzen, um den Fortschritt Ihrer Nutzenden nachzuvollziehen, Berichte zu erstellen und sicherzustellen, dass alle die erforderlichen Schulungen absolvieren. Das macht es einfacher, sicheres Verhalten zu fördern.
Warum ist die API für unsere Kunden und Partner wichtig?
Die API bietet Kunden und Partnern automatisierten Zugriff auf ihre Daten zu den Cybersicherheitsschulungen. Der Manager und sein Datenexport stehen weiterhin zur Verfügung, mit der API können Sie die Daten aber direkt in Ihre eigenen Arbeitsabläufe integrieren und flexibler verwalten.
Kunden und Partner möchten SoSafe-Daten oft für Zwecke wie diese nutzen:
- Reporting: Schulungsdaten können automatisiert abgerufen werden, um Berichte zu erstellen, die genau an Ihre Zwecke angepasst sind.
- Integration in interne Systeme: Organisationen möchten SoSafe-Schulungsdaten oft in ihre internen Sicherheits- oder HR-Systeme einspeisen, um die Schulungen der Mitarbeitenden zusammen mit anderen Unternehmenskennzahlen im Blick zu haben.
- Wissens-Dashboards erstellen: Kombinieren Sie unsere Daten mit anderen Datenquellen, die Ihnen zur Verfügung stehen, um eigene Dashboards zu erstellen, die Lernfortschritte zeigen und verbesserungsbedürftige Bereiche identifizieren.
Für Partner bietet die API weitere Möglichkeiten:
- Integration von SoSafe-Schulungsdaten in Ihre eigenen Lösungen: Als Partner können Sie Integrationen erstellen, um SoSafe-Schulungsdaten in Ihre Produkte und Dienstleistungen einzubinden und Ihren Kunden so zusätzliche Funktionen zu bieten.
- Kombinierte Lösungen: Durch die Kombination von E-Learning-Daten mit anderen Tools oder Diensten können Sie Ihren Kunden umfassende Sicherheits- oder Schulungslösungen bieten.
Ohne die API müssen Sie die Daten manuell in der SoSafe-Oberfläche zusammentragen. Dadurch ist es schwieriger, auf Grundlage der Daten zu handeln.
Was ist eine API?
Eine API, kurz für Application Programming Interface, ist eine Schnittstelle, über die zwei verschiedene Systeme bzw. Programme miteinander kommunizieren und Informationen austauschen können. Sie können sich die API als Brücke zwischen der Software Ihres Unternehmens und SoSafe vorstellen. Anstatt sich manuell bei SoSafe anzumelden, um Daten abzurufen, kann Ihr System die Daten über die API automatisch abrufen, wenn Sie sie benötigen, und sie so verarbeiten, wie Ihre Organisation es braucht.
Derzeitige Einschränkungen
Im Moment liefert die API nur Daten zum E-Learning und zu Phishing-Simulationen.
Technische Dokumentation
Die REST-API von SoSafe bietet Zugriff auf Nutzer-, E-Learning- und Phishing-Simulationsdaten unserer Plattform und ermöglicht so eine Integration in Ihre Systeme. Die Daten werden standardmäßig im JSON-Format geliefert, was eine einfache Weiterverarbeitung ermöglicht. Durch die Nutzung der SoSafe-API erklären Sie sich mit unseren Nutzungsbedingungen einverstanden.
Unsere APIs verwenden ressourcenorientierte URLs, Standard-HTTP-Methoden und Antwortcodes zur Fehlerbehandlung. Bei der Integration und Fehlerbehebung unterstützen wir Sie.
Im Folgenden finden Sie grundlegende Informationen. Die vollständige technische Dokumentation finden Sie in den OpenAPI-Spezifikationen.
Voraussetzungen
Zur Verwendung der SoSafe-API benötigen Sie:
- Ein laufendes SoSafe E-Learning und / oder eine laufende Phishing-Simulation
- Zugriff auf die API-Key-Verwaltungsseite im SoSafe Manager
- Wenn Sie keinen Zugriff auf diese Seite haben, klären Sie bitte mit Ihrer SoSafe-Kontaktperson, ob Sie das nötige Paket für die Verwendung von Analytics-Integrationen haben
- Technisches Know-how im Umgang mit APIs
Basis-URL
Die Basis-URL für alle API-Anfragen ist https://connect.sosafe.de.
Authentifizierung
Um auf die SoSafe-API zuzugreifen, authentifizieren Sie sich mit einem API-Schlüssel und einem Session-Token:
- API-Schlüssel generieren: Generieren Sie im Manager einen API-Schlüssel. Mit diesem Schlüssel fordern Sie Session-Tokens an, er gewährt aber keinen direkten Zugriff auf die API. Wählen Sie beim Erstellen die Bereiche (Scopes) aus, die Sie für Ihre geplanten API-Anfragen benötigen.
-
Anmelden, um ein JSON Web Token (JWT) zu erhalten: Senden Sie einen POST-Request an
/v1/auth/loginmit Ihrem API-Schlüssel im HeaderX-Api-Key. Eine gültige Anfrage gibt ein kurzlebiges JWT-Session-Token zurück. -
API-Requests ausführen: Fügen Sie das JWT im Header
Authorization: Bearer <jwt>ein, um auf die API zuzugreifen. - Token erneuern: Sobald das Token abgelaufen ist, verwenden Sie den API-Schlüssel erneut, um ein neues JWT-Session-Token anzufordern.
Aus Sicherheitsgründen müssen API-Requests über HTTPS gesendet werden. Kompromittierte API-Schlüssel können im Manager widerrufen werden.
Antwortformat
Die SoSafe-API liefert Antworten im JSON-Format. Alle Datums- und Zeitangaben folgen dem UTC-Standard (Koordinierte Weltzeit), damit die Angaben unabhängig von Zeitzonen nachvollziehbar bleiben.
API-Versionen
Die API wird über das erste Segment des URL-Pfads versioniert, zum Beispiel /v1/users oder /v2/learning/analytics. Bestehende /v1-Endpunkte funktionieren weiterhin, neue Endpunkte werden unter /v2 veröffentlicht.
Endpunkte, die abgeschaltet werden, sind in den OpenAPI-Spezifikationen als veraltet (deprecated) markiert und liefern die Header Deprecation, Sunset und Link zurück, die auf den jeweiligen Nachfolger verweisen.
Antwort-/Fehlercodes
SoSafe verwendet Standard-HTTP-Antwortcodes, um das Ergebnis einer API-Anfrage anzuzeigen.
- 2xx: Erfolgreich
- 4xx: Fehler auf der Clientseite (z. B. fehlender Parameter, Nutzer nicht gefunden)
- 5xx: Fehler auf der Serverseite (z. B. interne Serverprobleme)
Fehlercodes
- 401: Nicht autorisiert — Ungültiger API-Schlüssel.
- 403: Verboten — Vorgang ist nicht erlaubt.
- 404: Nicht gefunden — Die Ressource ist nicht verfügbar (z. B. Nutzer, Kampagne).
- 500: Interner Serverfehler — Versuchen Sie es später erneut.
- 503: Dienst nicht verfügbar — Laufende Wartung.
Sicherheit
Gehen Sie sorgfältig mit API-Schlüsseln um:
- Geben Sie so wenigen Mitarbeitenden wie möglich Zugriff auf den Bereich zur Schlüsselverwaltung und die generierten Schlüssel
- Nehmen Sie API-Schlüssel nicht fest in Ihren Code auf und checken Sie sie nicht in Code-Repositories ein
- Grenzen Sie die Scopes der Schlüssel so weit wie möglich ein
- Richten Sie einen Prozess zur Schlüsselrotation ein
- Entfernen Sie nicht mehr benötigte Schlüssel so bald wie möglich
Users-Endpunkt
Der Users-Endpunkt /v1/users ermöglicht den Zugriff auf eine Liste der Nutzer Ihres Kontos. Abrufbar sind Informationen wie Name, E-Mail-Adresse, Level, Nutzergruppe, benutzerdefinierte Attribute und Status (aktiviert/deaktiviert).
Beispiele
-
Liste aller Nutzer abrufen
Die vollständige Liste aller Nutzer abrufen, inklusive Attributen wie Name, E-Mail-Adresse, Level, Nutzergruppe und benutzerdefinierten Feldern. -
Liste bestimmter Nutzer abrufen
Daten zu bestimmten Nutzern mit zusätzlichen Filtern abrufen:- Nach Nutzergruppe filtern: Nur Nutzer aus einer bestimmten Gruppe abrufen.
- Nach E-Learning-Kampagne filtern: Nur Nutzer abrufen, die Teil einer bestimmten E-Learning-Kampagne sind.
E-Learning-Endpunkte
Kampagnen-Endpunkt
Der Kampagnen-Endpunkt /v1/campaigns/elearning bietet Zugriff auf die Liste der E-Learning-Kampagnen, die auf Ihrem Konto laufen. Sie erhalten dabei Informationen wie den Namen, Start- und Endzeitpunkt sowie die ID einer Kampagne. Die ID ist besonders hilfreich als Filter für die anderen Endpunkte.
Analytics-Endpunkt (V2)
Der E-Learning-Endpunkt /v2/learning/analytics ersetzt den Endpunkt /v1/analytics/elearning und bietet Zugriff auf Fortschrittsdaten zu zugewiesenen Modulen und Kampagnen. Er funktioniert nur für Kampagnen mit Personalisiertem Lernen. Die Filter werden als JSON im Request-Body gesendet (POST-Request). Die zurückgegebenen Daten können Sie anschließend weiter filtern, um bestimmte Informationen herauszuziehen.
Mit dem Header Accept-Language können Sie die Sprache der Antwort auswählen. Verfügbar sind Englisch (en), Deutsch (de) und Französisch (fr), bei allen anderen Sprachen wird Englisch zurückgegeben.
Neu im Vergleich zum bisherigen Endpunkt:
- Alle Daten zum Personalisierten Lernen: Die Antwort enthält dieselben Daten wie der Datenexport für Personalisiertes Lernen, zum Beispiel den Lernstatus, überfällige Pflichtmodule und die verantwortliche Person
- Expertenfilter: Filtern Sie nach benutzerdefinierten Feldern, Nutzergruppen-IDs, Sprache und Nutzertyp (siehe unten)
-
Einfacher zu verarbeiten: Werte verwenden native Datentypen (
true/falsestattYES/NO,nullstatt0oder leerem Text),extendedDatahat in jeder Zeile dieselben Schlüssel, und jede Antwort enthält die Gesamtzahl der Ergebnisse (totalDataAmount) für die Paginierung
Wenn Sie vom bisherigen Endpunkt wechseln, beachten Sie außerdem diese Änderungen:
- Filter werden im Request-Body statt im Query-String gesendet
- Parameter wurden umbenannt:
emailIdheißt jetztemailAddressunduserGroupheißt jetztuserGroupName -
moduleSplitType(all/mandatory/optional) heißt jetztisModuleSplit(-1/1/0). Standardmäßig werden jetzt nur Pflichtmodule statt aller Module berücksichtigt - IDs werden als Strings zurückgegeben:
userId,customerId,campaignIdundgroupIdinpassedModuleData. Filter im Request-Body, z. B.campaignId, erwarten weiterhin Zahlen - Die Nutzergruppen-ID wird nicht mehr zurückgegeben, nur noch der Name der Nutzergruppe. Die
groupIdinpassedModuleDataist die ID der Gruppe, zu der das Modul gehört, nicht die der Nutzergruppe - Ob dynamische oder nicht dynamische Nutzergruppen zurückgegeben werden, richtet sich jetzt nach der Einstellung Ihres Kontos (
dynamicGroupDataist nicht mehr verfügbar) - Es werden nur aktive Nutzer berücksichtigt
- Einige Felder der Antwort wurden umbenannt oder hinzugefügt. Details finden Sie in den OpenAPI-Spezifikationen
Folgende Filter können Sie im Request-Body setzen:
-
campaignId: Liste von Kampagnen-IDs (Pflichtfeld). Mit[0]rufen Sie kumulierte Daten über alle Kampagnen ab -
isModuleSplit:-1für alle Module,0für optionale Module,1für Pflichtmodule (Standard) -
emailAddress: Liste von E-Mail-Adressen -
userGroupName: Liste von Nutzergruppennamen -
expertFilters: Expertenfiltercf1biscf10(benutzerdefinierte Felder),userGroupId(Nutzergruppen-IDs),languageundtype. Nur verfügbar, wenn Ihr Konto erweiterte Nutzerdaten verwendet-
type: Art der Empfängeradresse.0= Einzeladresse,1= Verteilerliste
-
-
pageundlimit: Paginierung (Standard: Seite1,1000Ergebnisse pro Seite)
In den OpenAPI-Spezifikationen finden Sie eine technische Übersicht über die abrufbaren Daten und wie diese Daten formatiert sind.
Beispiele
-
E-Learning-Fortschritt aller Kampagnen abrufen
Kumulierte Fortschrittsdaten über alle Kampagnen abrufen, indem Sie[0]alscampaignIdsenden. -
E-Learning-Fortschritt einer bestimmten Kampagne abrufen
Fortschrittsdaten für eine oder mehrere bestimmte E-Learning-Kampagnen abrufen, indem Sie deren IDs alscampaignIdsenden. -
E-Learning-Fortschritt eines bestimmten Nutzers abrufen
Den detaillierten Fortschritt eines bestimmten Nutzers abrufen, indem Sie nachemailAddressfiltern. -
E-Learning-Fortschritt einer Nutzergruppe abrufen
Fortschrittsdaten einer bestimmten Nutzergruppe abrufen, indem Sie nachuserGroupNamefiltern. -
E-Learning-Fortschritt für ein bestimmtes Modul abrufen
Die zurückgegebenen Daten nach Modul filtern, um den detaillierten Fortschritt für ein bestimmtes Modul zu sehen. -
E-Learning-Fortschritt für den Wert eines benutzerdefinierten Felds abrufen
Die Daten mitexpertFiltersnach benutzerdefinierten Feldern filtern. Die verfügbaren Werte rufen Sie über den Expertenfelder-Endpunkt ab (siehe unten).
Analytics-Endpunkt (V1)
Der Endpunkt /v1/analytics/elearning ist veraltet und wird am 3. November 2027 entfernt. Bitte verwenden Sie stattdessen den Endpunkt /v2/learning/analytics (siehe oben).
Der E-Learning-Endpunkt /v1/analytics/elearning bietet Zugriff auf Fortschrittsdaten zu zugewiesenen Modulen und Kampagnen. Die zurückgegebenen Daten können Sie anschließend weiter filtern, um bestimmte Informationen herauszuziehen.
Beispiele
-
E-Learning-Fortschritt aller Nutzer abrufen
Fortschrittsdaten aller Nutzer über alle zugewiesenen E-Learning-Inhalte abrufen. -
E-Learning-Fortschritt eines bestimmten Nutzers abrufen
Den detaillierten Fortschritt eines bestimmten Nutzers abrufen. -
E-Learning-Fortschritt einer Nutzergruppe abrufen
Fortschrittsdaten einer bestimmten Nutzergruppe abrufen. -
E-Learning-Fortschritt aller Kampagnen abrufen
Fortschrittsberichte über alle E-Learning-Kampagnen abrufen. -
E-Learning-Fortschritt einer bestimmten Kampagne abrufen
Fortschrittsdaten für eine bestimmte E-Learning-Kampagne abrufen. -
E-Learning-Fortschritt für ein bestimmtes Modul abrufen
Die zurückgegebenen Daten nach Modul filtern, um den detaillierten Fortschritt für ein bestimmtes Modul zu sehen.
Expertenfelder-Endpunkt
Der E-Learning-Endpunkt /v2/learning/analytics/expert-fields liefert die Werte der benutzerdefinierten Felder, die in Ihrem Konto verfügbar sind. Damit können Sie die expertFilters für den Endpunkt /v2/learning/analytics zusammenstellen. Diese Werte stammen aus Ihren eigenen Daten und werden daher nicht übersetzt.
Zurückgegeben werden:
- Kunden-ID
- Schlüssel des benutzerdefinierten Felds zur Verwendung in
expertFilters(z. B.cf1) - Name des benutzerdefinierten Felds
- Wert des benutzerdefinierten Felds
Mit den optionalen Parametern page und limit können Sie die Ergebnisse paginieren. Der Endpunkt ist nur verfügbar, wenn Ihr Konto erweiterte Nutzerdaten verwendet.
In den OpenAPI-Spezifikationen finden Sie eine technische Übersicht über die abrufbaren Daten und wie diese Daten formatiert sind.
Phishing-Simulations-Endpunkte
Kampagnen-Endpunkt
Mit dem Endpunkt /v1/phishing-simulation/campaigns erhalten Sie eine Liste aller aktuellen und archivierten Phishing-Simulationen (auch als Kampagnen bezeichnet).
Zurückgegeben werden:
- Kampagnen-ID (mit dieser ID können Sie über den Endpunkt
/v2/phishing-simulation/analyticsdie Analytics zu dieser Kampagne abrufen, siehe unten) - Kampagnen-Name
- Start- und Enddatum der Kampagne
- Kampagnen-Status:
WAITING, ACTIVE, FINISHED, PAUSED, INACTIVE, PENDING, ALLOWLISTING_PENDING, SCHEDULED - Kampagnen-Version
- Archivstatus (
true, false) - Verfügbarkeit von Analytics (
true, false)
In den OpenAPI-Spezifikationen finden Sie eine technische Übersicht über die abrufbaren Daten und wie diese Daten formatiert sind.
Analytics-Endpunkt (V2)
Der Endpunkt /v2/phishing-simulation/analytics ersetzt den Endpunkt /v1/phishing-simulation/analytics und liefert auf die gleiche Weise detaillierte Daten zu Ihren Phishing-Simulationen (die verfügbaren Attribute finden Sie unter Analytics-Endpunkt (V1) weiter unten), mit einer Zeile pro simulierter Phishing-Mail. Die Antwort verwendet dasselbe Exportformat wie die Analytics im SoSafe Manager. Die Filter werden als JSON im Request-Body gesendet (POST-Request). Vorname, Nachname und E-Mail-Adresse sind null, wenn die Kampagne keine Nutzerdaten in Reports erlaubt.
Mit dem Header Accept-Language können Sie die Sprache von Template-Namen und Mail-Status auswählen. Verfügbar sind Englisch (en), Deutsch (de) und Französisch (fr), bei allen anderen Sprachen wird Englisch verwendet.
Neu im Vergleich zum bisherigen Endpunkt:
- Expertenfilter: Filtern Sie nach benutzerdefinierten Feldern, Nutzergruppen-IDs, Sprache und Nutzertyp (siehe unten)
-
Datumsfilter: Filtern Sie nach dem Versanddatum der Mail (
fromundto) - Kunden- und Kampagnen-IDs in jeder Zeile, nicht nur die Namen
-
Einfacher zu verarbeiten: Werte verwenden native Datentypen (
true/falsestattYes/No,nullstatt leerem Text),extendedDatahat in jeder Zeile dieselben Schlüssel, und jede Antwort enthält die Gesamtzahl der Ergebnisse (totalDataAmount) für die Paginierung
Wenn Sie vom bisherigen Endpunkt wechseln, beachten Sie außerdem diese Änderungen:
- Filter werden im Request-Body statt im Query-String gesendet
-
userGroupheißt jetztuserGroupName, unduserGroupIdist jetzt Teil vonexpertFilters - IDs werden als Strings zurückgegeben:
templateId,campaignIdundcustomerId. Filter im Request-Body, z. B.campaignId, erwarten weiterhin Zahlen - Die Nutzergruppen-ID (
organizeId) wird nicht mehr zurückgegeben, nur noch der Name der Nutzergruppe - Ob dynamische oder nicht dynamische Nutzergruppen zurückgegeben werden, richtet sich jetzt nach der Einstellung Ihres Kontos (
dynamicGroupDataist nicht mehr verfügbar) - Einige Felder der Antwort wurden umbenannt, zum Beispiel heißt
firstNamejetztuserFirstNameundansweredjetztreplied. Details finden Sie in den OpenAPI-Spezifikationen
Folgende Filter können Sie im Request-Body setzen:
-
campaignId: Liste von Kampagnen-IDs (Pflichtfeld). Mit[0]rufen Sie kumulierte Daten über alle Kampagnen ab -
fromundto: Zeitraum (yyyy-mm-dd, inklusive) bezogen auf das Versanddatum der Mail. Beide müssen zusammen angegeben werden -
userGroupName: Liste von Nutzergruppennamen -
expertFilters: Expertenfiltercf1biscf10(benutzerdefinierte Felder),userGroupId(Nutzergruppen-IDs),languageundtype. Nur verfügbar, wenn Ihr Konto erweiterte Nutzerdaten verwendet-
type: Art der Empfängeradresse.0= Einzeladresse,1= Verteilerliste
-
-
pageundlimit: Paginierung (Standard: Seite1,1000Ergebnisse pro Seite)
In den OpenAPI-Spezifikationen finden Sie eine technische Übersicht über die abrufbaren Daten und wie diese Daten formatiert sind.
Analytics-Endpunkt (V1)
Der Endpunkt /v1/phishing-simulation/analytics ist veraltet und wird am 3. November 2027 entfernt. Bitte verwenden Sie stattdessen den Endpunkt /v2/phishing-simulation/analytics (siehe oben).
Mit dem Endpunkt /v1/phishing-simulation/analytics können Sie detaillierte Informationen zu Ihren Phishing-Simulationen abrufen. Die verfügbaren Daten entsprechen den Daten, die Sie in den Analytics über Exporte / Daten herunterladen erhalten. Sie erhalten also Zugriff auf eine Liste aller versendeten simulierten Phishing-Mails mit diesen Attributen:
- Template-Name & ID
- Betreff der E-Mail
- Vor- und Nachname des Empfängers
- Absendername
- Sprache
- Nutzergruppe
- Status der E-Mail, inkl. Versanddatum
- Interaktionsinfo (Datum, an dem die E-Mail geöffnet, der Link geklickt, mit der Simulation interagiert, die Lernseite besucht, auf die E-Mail geantwortet und die E-Mail gemeldet wurde, sofern vorhanden)
- Ob ein mobiles Gerät verwendet wurde
- Name des Mandanten und der Kampagne
Mithilfe dieser Daten können Sie eigene KPIs berechnen oder die KPIs von SoSafe nachbilden. Wie letztere berechnet werden, erfahren Sie im Analytics-Bereich der Knowledge Base.
In den OpenAPI-Spezifikationen finden Sie eine technische Übersicht über die abrufbaren Daten und wie diese Daten formatiert sind.
Expertenfelder-Endpunkt
Der Endpunkt /v2/phishing-simulation/analytics/expert-fields liefert die Werte der benutzerdefinierten Felder, die für eine Phishing-Simulation (auch als Kampagne bezeichnet) verfügbar sind. Damit können Sie die expertFilters für den Endpunkt /v2/phishing-simulation/analytics zusammenstellen. Diese Werte stammen aus Ihren eigenen Daten und werden daher nicht übersetzt.
Die Parameter:
-
campaignId: Kampagnen-ID (Pflichtfeld). Mit0rufen Sie die Werte über alle Kampagnen ab -
pageundlimit: Paginierung (optional)
Das benutzerdefinierte Feld organize_id entspricht userGroupId in den Expertenfiltern. Der Endpunkt ist nur verfügbar, wenn Ihr Konto erweiterte Nutzerdaten verwendet.
In den OpenAPI-Spezifikationen finden Sie eine technische Übersicht über die abrufbaren Daten und wie diese Daten formatiert sind.
Zusätzliche Bedingungen
Sie können die aktuelle Version der zusätzlichen Bedingungen für die SoSafe-API unter Zusätzliche Bedingungen „SoSafe-API“ abrufen.