SoSafe API

Einführung

Wozu dient die SoSafe-API?

Die SoSafe API (Programmierschnittstelle) ermöglicht es Kunden und Partnern wie Ihnen, direkt über Software auf wichtige Informationen über die Cybersicherheits-Maßnahmen, die mit SoSafe durchgeführt werden, zuzugreifen. Die Daten können angeschaut und heruntergeladen werden, ohne den Manager zu verwenden. Mit der API können Sie automatisch zum Beispiel Informationen dieser Art abrufen:

• Mitarbeiterinformationen: Wer nimmt an Ihren SoSafe-Awarenessmaßnahmen teil?
• Schulungsfortschritt: Wie weit sind Ihre Mitarbeitenden mit den Schulungen bisher gekommen?
• Abgeschlossene Lektionen: Wer hat seine welche Lektionen bereits abgeschlossen?
• 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 mit diesen Informationen also 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 öffentlich zugängliche API ergänzt das bisherige Angebot von SoSafe, indem es Kunden und Partnern einen automatisierbaren Zugang auf Daten zu den Cybersicherheits-Schulungen bietet. Der SoSafe-Manager und die bestehende Datenexportfunktion sind zuverlässige Werkzeuge, allerdings ermöglicht die API neue Möglichkeiten, Daten effizienter und flexibler zu verwalten, da eine direkte Integration in Ihre Arbeitsabläufe möglich ist.

Viele unserer Kunden und Partner haben den Wunsch geäußert, SoSafe-Daten für verschiedene Zwecke in Ihren Organisationen zu nutzen. Dazu gehören:

• Reporting: Schulungsdaten können automatisiert abgerufen werden, um Berichte zu erstellen, die genau an Ihre Zwecke angepasst sind.
• Integration in interne Systeme: Durch das Einspeisen von SoSafe-Schulungsdaten können bestehende Sicherheits- oder HR-Systeme mit weiteren Daten angereichert werden und so ein vollständigeres Bild der Schulungsdaten oder anderer Kennzahlen ermöglichen.
• Wissens-Dashboards erstellen: Kombinieren Sie unsere Daten mit anderen Datenquellen, die Ihnen zur Verfügung stehen, um Ihre eigenen Dashboards zu erstellen, die Lernfortschritte zeigen oder verbesserungsbedürftige Bereiche identifizieren.

Für Partner bietet die API ebenfalls neue 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 so Ihren Kunden Mehrwert bieten.
• Kombinierte Lösungen: Durch die Fusion aus E-Learning-Daten mit anderen Tools oder Diensten können Sie Ihren Kunden umfassende Sicherheits- und Schulungslösungenbieten.

Zusammengefasst: Ohne die API war es nur möglich, manuell über das SoSafe-Interface auf Daten zuzugreifen. Dadurch war es schwieriger, diese Daten effektiv zur Entscheidungsfindung zu verwenden.

Was ist eine API?

Eine API, eine Abkürzung 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. Anstelle sich manuell im SoSafe Manager einzuloggen, können Sie mit der API autoamtisch Daten abfragen und es so Ihrer Software ermöglichen, die Daten so zu verwenden, wie es für Sie am besten ist.

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 Zugang zu Nutzerdaten und E-Learning-Daten unserer Plattform und ermöglicht so eine Integration mit Ihren Systemen. 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 unserne Nutzungsbedingungen einverstanden.

Unsere APIs verwenden ressourcenorientierte URLs, Standard HTTP-Methoden und Antwortcodes zur Fehlerbehandlung. Die API ist für Premium-Kunden verfügbar und bieten bei der Integration und Fehlerbehebung Support an.

Es folgen grundlegende Informationen. Die vollständige technische Dokumentation finden Sie in der OpenAPI-Spezifikation.

Voraussetzungen

Zur Verwendung der SoSafe-API benötigen Sie:

• laufendes SoSafe E-Learning und / oder Phishing-Simulation
• Zugriff auf die API-Key-Verwaltungsseite im SoSafe Manager​
  • Wenn Sie keinen Zugriff auf diese Seite haben, melden Sie Sich bitte bei Ihrer SoSafe-Kontaktperson, um zu überprüfen, ob sie auf dem nötigen Paket für die Verwendung der Analytics-Integration sind
• Technisches Know-How bzgl. der Arbeit mit APIs

Base URL

Stellen Sie sicher, dass Sie bei API-Anfragen die richtige Basis-URL für Ihres Konto verwenden. Im Regelfall ist dies https://connect.sosafe.de.

Authentifizierung

Um auf die SoSafe-API zuzugreifen, müssen Sie sich zunächst mithilfe eines API-Schlüssels und eines Session-Tokens anmelden.

1. API-Schlüssel generieren: Sie können im Manager API-Schlüssel generieren. Mithilfe dieses Schlüssels können Sie ein Session-Token anfragen, sich aber nicht direkt im API anmelden. Gehen Sie beim Erstellen der Schlüssel sicher, dass Sie die Bereiche auswählen, die sie für die geplanten API-Anfragen benötigen werden.
2. Login für das JSON Web Token (JWT): Senden Sie einen POST-Request an /auth/login und schicken den API-Schlüssel im X-Api-Key-Header mit. Eine valide Anfrage gibt ein JWT session token mit kurzer Lebensdauer zurück.
3. API-Requests ausführen: Fügen sie das JWT im Header Authorization: Bearer <jwt> an, um Zugriff auf die API zu erhalten.
4. Token erneuern: Sobald das Token abläuft, können Sie den API-Schlüssel verwenden, um ein neues JWT Session Token zu erstellen.

Aus Sicherheitsgründen müssen API-Requests über das HTTPS-Protokoll gesendet werden. Möglicherweise kompromittierte API-Schlüssel können im Manager widerrufen werden.

Antwortformat

Die SoSafe-API liefert Antworten im JSON-Format. Alle Datums- und Zeitangaben folgem dem UTC-Standard (Koordinierte Weltzeit), damit die Angaben unabhängig von Zeitzonen nachvollziehbar bleiben.

Users-Endpunkt

Der Endpunkt Users /users ermöglicht den Zugriff auf eine Liste von Nutzern, die mit dem jeweiligen Kunden verbunden sind. Abrufbar sind Informationen wie der Name, die E-Mail-Adresse, das Level, Nutzergruppen, benutzerdefinierte Attribute und der Status (aktiviert/deaktiviert).

Beispiele:

• Liste aller Nutzer abrufen

Liefert eine vollständige Liste aller Nutzer, inklusive ihrer Attribute wie Name, E-Mail-Adresse, Level, Nutzergruppe und weiteres.

• Liste bestimmter Nutzer abrufen

Sie können auch alle Nutzer abrufen, die bestimmten Filtern entsprechen:

Nach Nutzergruppe filtern: Nur Nutzer aus einer bestimmten Gruppe abrufen.

Nach E-Learning-Kampagne: Nur Nutzer abrufen, die Teil einer bestimmten E-Learning-Kampagne sind.

E-Learning-Endpunkte

Kampagnen-Endpunkt

Der Kampagnen-Endpunkt /campaign/elearning bietet Zugriff auf eine Liste der E-Learning-Kampagnen an, die auf Ihrem Konto laufen. Sie erhalten dabei Informationen wie den Namen, Start- und Endzeitpunkt und auch IDs. Letztere sind besonders hilfreich als Filter in anderen Endpunkten.

Analytics-Endpunkt

Der Analytics-Endpunkt /analytics/elearning bietet Zugriff auf Fortschrittsdaten zu den zugewiesenen Lektionen und Kampagnen.

Beispiele

• E-Learning-Fortschritt aller Nutzer abrufen

Abrufen der Fortschrittsdaten für alle Nutzer über alle zugewiesenen Lerninhalte.

• E-Learning-Fortschritt einen bestimmten Nutzer abrufen

Detaillierter Fortschrittsbericht über einen bestimmten Nutzer.

• E-Learning-Fortschritt einer Nutzergruppe abrufen

Abrufen der Fortschrittsdaten einer bestimmten Nutzergruppe.

• E-Learning-Fortschritt aller Kampagnen abrufen

Fortschrittsbericht über alle Kampagnen hinweg.

• E-Learning-Fortschritt einer Kampagne abrufen

Abrufen der Fortschrittsdaten für eine bestimmte Kampagne.

• E-Learning-Fortschritt für eine bestimmte Lektion abrufen

Detaillierter Fortschrittsbericht für eine bestimmte Lektion.

Phishing-Simulationen-Endpunkte

Kampagnen-Endpunkt

Mit dem Endpunkt für Phishing-Simulationen /phishing-simulation/campaigns erhalten Sie eine Liste aller Phishing-Simulationen (auch als Kampagnen bezeichnet).

Die je Kampagne zur Verfügung gestellten Daten:

• Kampagnen-ID (mit dieser ID können über den Endpunkt /phishing-simulation/analytics die Analytics zu dieser Kampagne abgerufen werden, s.u.)
• Kampagnen-Name
• Start- und End-Datum 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

Mit dem Endpunkt für Phishing-Simulationen /phishing-simulation/analytics können Sie detaillierte Informationen zu Ihren Phishing-Simulationen abrufen. Die verfügbaren Daten entsprechen dabei dem Menüpunkt “Daten herunterladen” in den Analytics. Sie erhalten entsprechen Zugriff auf die Daten aller simulierten Phishing-Mails:

• Template ID & Name
• 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 wurde, mit ihr interagiert wurde, die Lernseite besucht wurde, auf die E-Mail geantwortet wurde und wann die E-Mail gemeldet wurde)
• Ob die Interaktion über ein mobiles Gerät erfolgte
• Name des Mandanten und der Kampagne

Mithilfe dieser Daten können Sie entweder eigene KPIs berechnen oder sich an den SoSafe-Kennzahlen orientieren. 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.

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 authorisiert — ungültiger API-Schlüssel
• 403: Verboten — Vorgang ist nicht erlaubt.
• 404: Nicht gefunden — Die Ressource ist nicht verfügbar (z.B. User, Kampagne)
• 500: Interner Serverfehler — Versuchen Sie es später erneut
• 503: Dienst nicht verfügbar — Laufende Wartung

Sicherheit

Gehen Sie mit API-Schlüssel sorgfältig um:

• geben Sie so wenig Mitarbeitenden wie möglich Zugriff auf den Bereich zur Schlüsselverwaltung und die generierten Schlüssel
• nehmen Sie API-Schlüssel nicht fest in Ihre Codebasis auf oder pflegen Sie sie nicht in Code-Repositories ein
• grenzen Sie den Scope der Schlüssel so weit wie möglich ein
• richten Sie eine Schlüsselrotation ein
• entfernen Sie nicht mehr benötigte Schlüssel so bald wie möglich

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.