Introduction
In early 2023, the SimpleRisk Team introduced a new version of the API dubbed "API v2". For now, the old API still exists under /api and the endpoints from it will slowly be migrated over to the new v2 API under /api/v2. Once we have feature parity, we will be obsoleting the old API in favor of the new one.
You may be asking yourself, "Why introduce a new API when the old one works?" If we are being honest with ourselves, the old API was pretty much a "bolt on" to the existing SimpleRisk functionality. The original application was largely built using dynamic PHP pages, with the API being added for latter functionality to give the application a more interactive feel. However, being that it was built primarily for utilization with the SimpleRisk UI, there are a number of endpoints that return non-programmatic output, such as HTML data.
The SimpleRisk API v2 was built with programmatic interactions in mind. It is a pure REST-based API, utilizing GET, POST, PUT and DELETE request methods and returning well-formatted JSON data. The eventual goal is to expand to utilize a Hypermedia as the Engine of Application State (HATEOAS) constraint on the REST application architecture.
Documentation
One of our biggest challenges with SimpleRisk API v1 was in keeping up-to-date documentation around the endpoint functionality that had been implemented. Initially, we created a "mock" page so that you could see what these requests looked like, but that required us to actually add the mock templates and modify them as changes were made. We also created an API User's Guide document that provided a list of endpoints, methods and parameters, but it was unorganized and difficult to understand. Both of these approaches fell short of the experience we wanted for our customers.
The SimpleRisk API v2 leverages a standard called Swagger to document functionality implemented as an API endpoint. We take comments in the code and use them to dynamically generate the Swagger JSON descriptor file located at /api/v2/swagger.php. As long as the appropriate comments are added to the code, this file is automatically updated. Additionally, we've added a new Documentation page which reads that Swagger JSON file and renders it in a functional web UI format, allowing you to not only view the various API endpoints, but also interact with them. You will find a link to this page labeled as "API Documentation" under the help menu in your SimpleRisk instance or you can navigate to it directly at /api/v2/documentation.php.
Authentication
The SimpleRisk API v2 supports 3 different methods of authentication with the API endpoints:
Authentication Method #1 (Session-Based Authentication): This is a carry-over from the API v1 functionality where you can use an existing session from the SimpleRisk application in order to authenticate an API call. This authentication method is only intended to provide users with a way to test out the ability to make requests to and receive responses from the API through a web browser and is not recommended for programmatic integrations with the API, as sessions are designed to terminate after a short period of inactivity.
Authentication Method #2 (Parameter-Based Authentication): The is a carry-over from the API v1 functionality where you can use a key parameter, sent via either GET or POST, to provide the application with the API key to authenticate the request. This method has been deemed insecure, as it exposes sensitive information (ie. the API key) in the URL, which can cause it to be leaked through caching, logging, shoulder surfing and various other attack vectors. It has been kept in the application for legacy support reasons, but should not be used to build any new integrations.
Authentication Method #3 (Header-Based Authentication): This is the only authentication method that you should be using for programmatic integrations with SimpleRisk. For this authentication method, an API key is specified in the X-API-KEY header that is sent along with each request to an API endpoint. When the application sees this header, it uses the sent API key to uniquely identify the user making the request.
Creating an API Key
The API keys which are used for Authentication Methods #2 and #3 can only be generated in SimpleRisk via the API Extra. This paid for feature of SimpleRisk enables users to generate their own API keys. Once the API Extra has been purchased, downloaded and activated, you can create an API key for your user by logging into your SimpleRisk instance, selecting your username in the top right corner, and then selecting "My Profile" from the drop down menu:
Scroll to just above the User Responsibilities section and you should see a line labeled API Key:
When you click on Generate API Key, you will be presented with a 100 character long randomly generated key consisting of upper case, lowercase and numeric characters. You should immediately copy this generated value into your password manager, as you will be unable to retrieve it again once you navigate away from this page or refresh it. At that point, your only options will be to Rotate API Key, which invalidates the existing key and generates a new one, or Invalidate API Key, which invalidates the existing key so that a key no longer exists for this user. You can only have a single API key for each user.
It is important to note that for all intents and purposes this API key works the same as a username and password combination and should be protected as such. It will receive the same permissions as the user it was generated for. You should take care not to expose it in a clear text format, whether in transit or at rest, and rotate it regularly.
Receiving Data from the SimpleRisk API
The API Documentation can now be accessed by selecting "API Documentation" under the help menu in your SimpleRisk instance or you can navigate to it directly at /api/v2/documentation.php. While the page will still work without specifying an API key due to the Session-Based Authentication described above, it is always best to specify an API key for proper testing with the Header-Based Authentication. To enter your API key, click on the "Authorize" button on the right side of the page, enter your API key into the value field, and click on "Authorize".
Down below, you will see the list of available API endpoints, broken up into sections based on the type of operations provided. Remember that while all available API endpoints are displayed, the provided API key will still need to be associated with a user who has the proper permissions to leverage that functionality. So if I am using an API key associated with an Administrator user, I can select the "GET /admin/version" endpoint and will note that no parameters are required to exercise this functionality and my API key will automatically be included in this request through an X-API-KEY header. We can see the potential responses to our query as well.
If I would like to exercise this request, I click on "Try it out" in the top right corner, followed by "Execute". In the resulting response, we will see a sample Curl query that we could run to get the same result along with the JSON response body and headers for the response that was just executed against our SimpleRisk instance. The JSON response body includes a status code, status_message and data array containing the result of the request. Your integrations should look to verify the response code before taking any actions based upon the data received.
It is worth noting that this functionality is not just a test. This will exercise the actual API endpoint functionality with the potential to modify your data as a result. We do not recommend using this against a Production SimpleRisk instance unless you have verified, in advance, that you are okay with the changes that it will make.