SoSafe API – SoSafe Support

Introduction

What does the SoSafe API do?

The SoSafe API allows customers and partners like you to access important information about their SoSafe cyber security measures directly in software, without having to log in and view or download information manually in the manager. With this API, you can automatically retrieve info including but not limited to:

Employee information: Who are the users enrolled in your SoSafe awareness measures?
Employee training progress: How far have your employees come in their cybersecurity training?
Lesson completion: Who has finished their lessons and who still have some left to do?
Team engagement: Get insights on how well different groups are engaging with the training.
Risk levels & secure behavior: How good are employees at spotting simulated phishing emails and how often do they report them?

You can use this information to track user progress, create reports, or make sure that everyone is keeping up with the required training. This will make it easier to drive secure behavior!

Why does it matter for our customers and partners?

The public-facing API enhances SoSafe's current offerings by providing seamless, automated access to cyber security training data for customers and partners. While SoSafe's manager and data export functionality have been reliable tools, the API opens up new possibilities for more efficient and flexible data management by allowing direct integration into your workflows.

Many of our customers and partners have expressed their desire to leverage SoSafe’s data for a variety of purposes across their organizations, such as:

Reporting: Automating the process of pulling training data to create custom reports tailored to your specific needs.
Integrating into internal systems: Organizations often want to feed SoSafe training data into their internal security or HR systems to get a complete view of employee training alongside other business metrics.
Building knowledge dashboards: You can use our data alongside any other data you might have access to in order to build custom dashboards to showcase training progress and identify areas that need improvement.

For partners, this API opens up additional possibilities:

Embedding SoSafe training data into your own solutions: As a partner you can build integrations that embed cybersecurity training data into your own products or services, offering value-added features for your clients.
Joint solutions: Combine SoSafe's e-learning data with other tools or services to create comprehensive security or training solutions for your customers.

Without the API, you could only manually interact with SoSafe’s interface to gather data, which limited your ability to act on and leverage the data effectively.

What is an API?

An API, which stands for Application Programming Interface, is a tool that allows two different systems or programs to talk to each other and share information. Think of it as a bridge between your company's software and SoSafe. Instead of manually logging into SoSafe to get data, the API lets your system automatically pull that data when you need it, giving your system the ability to do with the data exactly what your organization needs it to do.

Current limitations

At the moment, the API is limited to E-Learning and Phishing Simulation data.

Technical Documentation

SoSafe's REST API provides access to user and e-learning data from our platform, enabling integration into your systems. All data is returned in JSON format by default, allowing for easy processing and customization. By using SoSafe's APIs, you agree to our Terms of Service.

Our APIs use resource-oriented URLs, standard HTTP methods, and response codes for error handling. These APIs are available to premium customers, with support provided for integration and troubleshooting.

You will find some basic information below. For the full technical documentation, please refer to the OpenAPI specification.

Prerequisites

To use the SoSafe API you will need:

A running SoSafe E-Learning and / or Phishing Simulation
Access to the SoSafe Manager API Key Management page
- If you don’t have access to this page, please check with your SoSafe contact person whether you are on the necessary package for using Analytics integrations
Technical know-how on how to work with APIs

Base URL

Ensure you use the correct base URL based on your account's location when making API requests. Usually, this should be https://connect.sosafe.de.

Authentication

To access SoSafe’s API, users must authenticate with a two-step process involving an API Key and a session token.

Generate API key: Obtain your API Key from the Manager portal. This key is used to request session tokens but not for direct API access. Make sure to select appropriate scopes depending on which API requests you intend to use later.
Login for JSON Web Token (JWT): Send a POST request to /auth/login with your API Key in the X-Api-Key header. A valid request returns a short-lived JWT session token.
Make API requests: Include the JWT in the Authorization: Bearer <jwt> header for API access.
Token renewal: Once expired, use the API Key again to obtain a new JWT session token.

For security, API requests must be made over HTTPS. Compromised API Keys can be revoked in the portal.

Response format

SoSafe’s API responses are formatted in JSON. All dates and times within the responses follow the UTC (Coordinated Universal Time) standard, ensuring consistency across different time zones.

Users endpoint

The Users endpoint /users allows access to a list of users associated with your account, returning relevant information such as name, email, user level, group, custom attributes, and status (enabled/disabled).

Example use cases:

Get list of all users

Retrieve the full list of users, including detailed attributes such as their name, email, user level, group, and custom fields.

Get list of specific users

Retrieve data for specific users with additional filtering options:

Filter by group: Return users belonging to a particular group.

Filter by learning campaign: Return users who are part of a specific e-learning campaign.

E-Learning endpoints

Campaigns endpoint

The campaigns endpoint /campaigns/elearningallows access to the list of e-learning campaigns running on your account. You will receive information such as the name and dates for a campaign as well as its id, which can be useful for filtering data from the other endpoints.

Analytics endpoint

The E-Learning endpoint /analytics/elearning allows retrieval of user progress related to assigned training modules and campaigns. After the data is returned, it can be filtered to extract specific information as required.

Example use cases

Get E-Learning progress for all users

Retrieve progress data for all users across all assigned e-learning content.

Get E-Learning progress of a particular user

Fetch detailed progress for a specific user.

Get E-Learning progress of a group of users

Retrieve progress data for a specified group of users.

Get E-Learning progress of all campaigns

Fetch progress reports across all e-learning campaigns.

Get E-Learning progress of a particular campaign

Retrieve progress for a specific e-learning campaign.

Get E-Learning progress of a particular module

Fetch detailed progress for a specific training module.

Phishing Simulation endpoints

Campaigns

The Phishing Simulation endpoint /phishing-simulation/campaigns allows retrieval of a list of current and archived Phishing Simulations (also known as campaigns).

The data returned include:

Campaign ID (which can be used to retrieve a campaign’s analytics using the endpoint /phishing-simulation/analytics (see below))
Campaign name
Campaign start & end date
Campaign status: WAITING, ACTIVE, FINISHED, PAUSED, INACTIVE, PENDING, ALLOWLISTING_PENDING, SCHEDULED
Campaign version
Archive status (true, false)
Analytics availability (true, false)

Please refer to the OpenAPI specifications for a technical interview of the data and the corresponding format.

Analytics

The Phishing Simulation endpoint /phishing-simulation/analytics allows retrieval of detailed phishing simulation data. The available data equals that available via Download data in the Analytics. This means you get access to a list of all simulated phishing mails sent, with the following attributes:

Template name & ID
Email subject
Recipient first and last name
Sender name
Language
User group
Mail status, including the date when it was sent
Interaction info (opened, clicked, interacted, learned, answered and reported dates if available)
Whether a mobile user agent was used
Tenant & campaign name

You can use these data as a starting point to build your own KPIs if desired or emulate SoSafe’s KPIs. To find out how the latter are calculated, consult the Analytics section in our Knowledge Base.