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?

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. Der Zugang auf weitere Daten wird folgen.

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
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 den Standort Ihres Kontos 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.

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.
Login für das JSON Web Token (JWT): Senden Sie einen POST-Request an /login und schicken den API-Schlüssel im X-Api-Key-Header mit. Eine valide Anfrage gibt ein JWT session token mit kurzer Lebensdauert zurück.
API-Requests ausführen: Fügen sie das JWT im Header Authorization: Bearer <jwt> an, um Zugriff auf die API zu erhalten.
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 v1/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.

Kampagnen-Endpunkt

Der Kampagnen-Endpunkt v1/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 v1/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.

Verfügbare Daten

In dem Bereich Schema der OpenAPI-Spezifikationen finden Sie eine Übersicht über die abrufbaren Daten für jeden Endpunkt 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 https://de.support.sosafe.de/WINFO/sosafe-api-nutzungsbedingungen abrufen.