SoSafe API
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.
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 data. Access to more data will follow.
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
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.
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
/login
with your API Key in theX-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 v1/users
allows access to a list of users associated with a 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.
Campaigns endpoint
The campaigns endpoint v1/campaign/elearning
allows 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 v1/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.
Available data
Please refer to the schema section of the OpenAPI specifications for an overview of which data is available for each endpoint and how it is formatted.
Response/error codes
SoSafe uses standard HTTP response codes to indicate the outcome of an API request.
2xx: Success
4xx: Client error (e.g., missing parameter, user not found)
5xx: Server error (e.g., internal server issue)
Error Codes
401: Unauthorized — Invalid API key.
403: Forbidden — Action not permitted.
404: Not Found — Resource not available (e.g., user, campaign).
500: Internal Server Error — Try again later.
503: Service Unavailable — Maintenance in progress.
Security considerations
Please treat API keys carefully:
limit access to the key management area and the created keys to just a few employees
do not hardcode API keys into your codebase or check them into code repositories
choose scopes appropriately
have a key rotation process in place
remove unneeded keys asap
Terms and Conditions
The current version of the terms and conditions are available at https://support.sosafe.de/INFO/sosafe-api-terms-and-conditions.