Setup Insomnia for IriusRisk API

Let’s first download insomnia, available here:

https://insomnia.rest/

Once we have downloaded and installed insomnia, you will want to get our library of API requests, available here at SwaggerHub (note: install the latest version, top left):

https://app.swaggerhub.com/apis/continuumsecurity/IriusRisk/1.18.0

- download available at export (top right) > download api > json unresolved

Once we have downloaded this file, we must import it into insomnia. This is very easy as shown below:

First, create a new project:

Next we can import the file we previously downloaded, containing all requests for the API. Simply click on one of the two locations to import > file:

Congratulations, we have now successfully imported the API requests:

The requests however will not work out of the box. We need to specify two things:

• Path variables
• Authentication – API Key

We can do this two ways:

Method 1: Setting globally (preferred)

Please note: this is the preferred method. This allows us to set the API key and the path once and it will work for all our requests.

We must provide authentication in the API, to do this we pass in an API Key, please use the following guide to generate an API key & make sure to note it:

https://support.iriusrisk.com/hc/en-us/articles/360021521291-Get-an-API-Key

Start by accessing our global (within the scope of the project) variables. We can find this at the top of the list of our requests. Click on the dropdown beside ‘swagger env’ then click ‘manage environments’:

From here we can set the environment variables. I recommend setting this in ‘swagger env’ to provide scope to the project as sometimes we may have multiple projects with different APIs and we may need separate url’s and api key’s:

As we can see from above, we have set the ‘base_url’ to our IriusRisk instance and the ‘api-token’ to the token we got previously. Click close (bottom right) to save.

We can test this has worked by navigating to a request, for this example I have used 'GET all users', but the request you use may be dependent on your role so please make sure you have correct access levels for your request:

Click send and observe the response:

Status 200, OK. We have got a successful response.

Note: remember to apply the change to the request. This can be done by applying it in the authentication type - api token auth, with 'api-token' and then calling the api-token as the value

or

by assigning it in the header as shown below:

Method 2: Setting locally

Please note: this method is not preferred as it requires repeating these steps on every single request

Please note: For this example, I have used GET all users, but the request you get may be dependent on your role so please make sure you have correct access levels for your request

Path variables

We start by removing the base_url and inserting our own, for example:

Demo.iriusrisk.com/api/v1/users

YOUR_INSTANCE_NAME.iriusrisk.com/api/v1/ENDPOINT

Authentication

We must provide authentication in the API, to do this we pass in an API Key, please use the following guide to generate an API key & make sure to note it:

https://support.iriusrisk.com/hc/en-us/articles/360021521291-Get-an-API-Key

Once we have our API Key, navigate to the request we want and use the navigation tabs to go to Auth and choose ‘API Key Auth’ as shown below:

From here, set the key to api-token and set the value to your api key as shown below:

Click send and observe the response:

Status 200, OK. We have got a successful response.

Alternative documentation is available for using postman instead of insomnia. Available here: https://support.iriusrisk.com/hc/en-us/articles/6558401569693-Setup-Postman-for-IriusRisk-API