SoSafe API – SoSafe Support

Introductie

Wat doet de SoSafe API?

De SoSafe API stelt klanten en partners zoals u in staat om rechtstreeks in software toegang te krijgen tot belangrijke informatie over hun SoSafe-cyberbeveiligingsmaatregelen, zonder dat u hoeft in te loggen en informatie handmatig in de manager hoeft te bekijken of te downloaden. Met deze API kunt u automatisch informatie ophalen, waaronder maar niet beperkt tot:

Medewerkersinformatie: Wie zijn de users die deelnemen aan uw SoSafe-bewustwordingsmaatregelen?
Voortgang van medewerkerstraining: Hoe ver zijn uw medewerkers gevorderd in hun cybersecuritytraining?
Lesafronding: Wie heeft zijn of haar lessen afgerond en wie heeft er nog enkele te gaan?
Betrokkenheid van teams: Krijg inzicht in hoe goed verschillende groepen betrokken zijn bij de training.
Risiconiveaus & veilig gedrag: Hoe goed zijn medewerkers in het herkennen van gesimuleerde phishingmails en hoe vaak melden zij deze?

U kunt deze informatie gebruiken om de voortgang van users bij te houden, rapporten te maken of ervoor te zorgen dat iedereen de vereiste training bijhoudt. Dit maakt het eenvoudiger om veilig gedrag te stimuleren!

Waarom is dit relevant voor onze klanten en partners?

De publiek toegankelijke API vergroot het huidige aanbod van SoSafe door klanten en partners naadloze, geautomatiseerde toegang te bieden tot gegevens over cybersecuritytraining. Terwijl de manager en de functionaliteit voor gegevensexport van SoSafe betrouwbare hulpmiddelen zijn geweest, biedt de API nieuwe mogelijkheden voor efficiënter en flexibeler gegevensbeheer door directe integratie in uw werkprocessen mogelijk te maken.

Veel van onze klanten en partners hebben de wens geuit om de gegevens van SoSafe voor uiteenlopende doeleinden te benutten binnen hun organisaties, zoals:

Rapportage: Het automatiseren van het ophalen van trainingsgegevens om aangepaste rapporten te maken die zijn afgestemd op uw specifieke behoeften.
Integratie in interne systemen: Organisaties willen SoSafe-trainingsgegevens vaak invoeren in hun interne beveiligings- of HR-systemen om een volledig overzicht te krijgen van de training van medewerkers naast andere bedrijfsstatistieken.
Kennisdashboards bouwen: U kunt onze gegevens combineren met andere gegevens waartoe u toegang heeft om aangepaste dashboards te maken die de trainingsvoortgang inzichtelijk maken en aandachtspunten identificeren.

Voor partners biedt deze API aanvullende mogelijkheden:

SoSafe-trainingsgegevens insluiten in uw eigen oplossingen: Als partner kunt u integraties bouwen die cybersecuritytrainingsgegevens insluiten in uw eigen producten of diensten, en zo meerwaarde bieden aan uw clients.
Gezamenlijke oplossingen: Combineer de e-learninggegevens van SoSafe met andere tools of diensten om uitgebreide beveiligings- of trainingsoplossingen te creëren voor uw klanten.

Zonder de API kon u alleen handmatig met de interface van SoSafe werken om gegevens te verzamelen, wat uw mogelijkheden om de gegevens effectief te gebruiken en te benutten beperkte.

Wat is een API?

Een API, wat staat voor Application Programming Interface, is een hulpmiddel waarmee twee verschillende systemen of programma's met elkaar kunnen communiceren en informatie kunnen uitwisselen. Beschouw het als een brug tussen de software van uw bedrijf en SoSafe. In plaats van handmatig in te loggen bij SoSafe om gegevens op te halen, stelt de API uw systeem in staat om die gegevens automatisch op te halen wanneer u ze nodig heeft, zodat uw systeem precies kan doen wat uw Organization met de gegevens nodig heeft.

Huidige beperkingen

Op dit moment is de API beperkt tot E-Learning- en Phishing Simulation-gegevens.

Technische documentatie

De REST API van SoSafe biedt toegang tot gebruikers- en e-learninggegevens van ons platform, waarmee integratie in uw systemen mogelijk wordt. Alle gegevens worden standaard geretourneerd in JSON-indeling, wat eenvoudige verwerking en aanpassing mogelijk maakt. Door gebruik te maken van de API's van SoSafe gaat u akkoord met onze Servicevoorwaarden.

Onze API's maken gebruik van resource-georiënteerde URL's, standaard HTTP-methoden en responscodes voor foutafhandeling. Deze API's zijn beschikbaar voor Premium-klanten, met ondersteuning voor integratie en probleemoplossing.

Hieronder vindt u enige basisinformatie. Raadpleeg voor de volledige technische documentatie de OpenAPI-specificatie.

Vereisten

Om de SoSafe API te gebruiken heeft u het volgende nodig:

Een actieve SoSafe E-Learning en/of Phishing Simulation
Toegang tot de pagina API Key Management in de SoSafe Manager
- Als u geen toegang heeft tot deze pagina, neem dan contact op met uw SoSafe-contactpersoon om te controleren of u het benodigde pakket heeft voor het gebruik van Analytics-integraties
Technische kennis over het werken met API's

Basis-URL

Zorg ervoor dat u de juiste basis-URL gebruikt op basis van de locatie van uw Account wanneer u API-verzoeken indient. Gewoonlijk zou dit https://connect.sosafe.de moeten zijn.

Authenticatie

Om toegang te krijgen tot de API van SoSafe moeten gebruikers zich authenticeren via een tweestaps-proces met een API-sleutel en een sessietoken.

API-sleutel genereren: Verkrijg uw API-sleutel via de Manager-portal. Deze sleutel wordt gebruikt om sessietokens aan te vragen, maar niet voor directe API-toegang. Zorg ervoor dat u de juiste scopes selecteert, afhankelijk van welke API-verzoeken u later wilt gebruiken.
Inloggen voor JSON Web Token (JWT): Stuur een POST-verzoek naar /auth/login met uw API-sleutel in de X-Api-Key-header. Een geldig verzoek retourneert een kortlopend JWT-sessietoken.
API-verzoeken indienen: Voeg het JWT toe aan de Authorization: Bearer <jwt>-header voor API-toegang.
Token vernieuwen: Gebruik na het verlopen de API-sleutel opnieuw om een nieuw JWT-sessietoken te verkrijgen.

Om veiligheidsredenen moeten API-verzoeken worden gedaan via HTTPS. Gecompromitteerde API-sleutels kunnen in de portal worden ingetrokken.

Responsindeling

De API-responsen van SoSafe zijn opgemaakt in JSON. Alle datums en tijden in de responsen volgen de UTC-standaard (Coordinated Universal Time), wat consistentie over verschillende tijdzones garandeert.

Users-endpoint

Het Users-endpoint /users biedt toegang tot een lijst van users die aan uw Account zijn gekoppeld, en retourneert relevante informatie zoals naam, e-mailadres, gebruikersniveau, groep, aangepaste kenmerken en status (ingeschakeld/uitgeschakeld).

Voorbeelden van gebruikssituaties:

Lijst van alle users ophalen

Haal de volledige lijst van users op, inclusief gedetailleerde kenmerken zoals naam, e-mailadres, gebruikersniveau, groep en aangepaste velden.

Lijst van specifieke users ophalen

Haal gegevens op voor specifieke users met aanvullende filteropties:

Filteren op groep: Retourneer users die tot een bepaalde groep behoren.

Filteren op leer-campaign: Retourneer users die deelnemen aan een specifieke e-learning-campaign.

E-Learning-endpoints

Campaigns-endpoint

Het Campaigns-endpoint /campaigns/elearning biedt toegang tot de lijst van E-Learning Campaigns die actief zijn op uw Account. U ontvangt informatie zoals de naam en datums van een campaign, evenals het ID ervan, wat nuttig kan zijn voor het filteren van gegevens uit de andere endpoints.

Analytics-endpoint

Het E-Learning-endpoint /analytics/elearning maakt het mogelijk om de voortgang van users op te halen met betrekking tot toegewezen trainingsmodules en Campaigns. Nadat de gegevens zijn geretourneerd, kunnen ze worden gefilterd om specifieke informatie te extraheren waar nodig.

Voorbeelden van gebruikssituaties

E-Learning-voortgang ophalen voor alle users

Haal voortgangsgegevens op voor alle users voor alle toegewezen E-Learning-inhoud.

E-Learning-voortgang ophalen van een specifieke user

Haal gedetailleerde voortgang op voor een specifieke user.

E-Learning-voortgang ophalen van een groep users

Haal voortgangsgegevens op voor een opgegeven groep users.

E-Learning-voortgang ophalen van alle Campaigns

Haal voortgangsrapporten op voor alle E-Learning Campaigns.

E-Learning-voortgang ophalen van een specifieke Campaign

Haal de voortgang op voor een specifieke E-Learning Campaign.

E-Learning-voortgang ophalen van een specifieke module

Haal gedetailleerde voortgang op voor een specifieke trainingsmodule.

Phishing Simulation-endpoints

Campaigns

Het Phishing Simulation-endpoint /phishing-simulation/campaigns maakt het mogelijk om een lijst op te halen van huidige en gearchiveerde Phishing Simulations (ook bekend als Campaigns).

De geretourneerde gegevens omvatten:

Campaign-ID (dat kan worden gebruikt om de Analytics van een campaign op te halen via het endpoint /phishing-simulation/analytics (zie hieronder))
Campaign-naam
Start- en einddatum van de campaign
Campaign-status: WAITING, ACTIVE, FINISHED, PAUSED, INACTIVE, PENDING, ALLOWLISTING_PENDING, SCHEDULED
Campaign-versie
Archiveringsstatus (true, false)
Beschikbaarheid van Analytics (true, false)

Raadpleeg de OpenAPI-specificaties voor een technisch overzicht van de gegevens en de bijbehorende indeling.

Analytics

Het Phishing Simulation-endpoint /phishing-simulation/analytics maakt het mogelijk om gedetailleerde phishing-simulatiegegevens op te halen. De beschikbare gegevens komen overeen met de gegevens die beschikbaar zijn via Download data in de Analytics. Dit betekent dat u toegang krijgt tot een lijst van alle gesimuleerde phishingmails die zijn verzonden, met de volgende kenmerken:

Templatenaam en -ID
E-mailonderwerp
Voor- en achternaam van de ontvanger
Naam van de afzender
Taal
User group
Mailstatus, inclusief de datum waarop de mail is verzonden
Interactie-informatie (datums van openen, klikken, interactie, leren, beantwoorden en melden, indien beschikbaar)
Of een mobiele user agent is gebruikt
Naam van tenant en campaign

U kunt deze gegevens gebruiken als uitgangspunt om, indien gewenst, uw eigen KPI's op te stellen of de KPI's van SoSafe na te bootsen. Hoe laatstgenoemde worden berekend, leest u in de sectie Analytics in onze Knowledge Base.