Getting Started
You will need to obtain several items in order to start using the Ivanti Neurons for RBVM/ASOC API. This guide will help you to complete the following tasks:
- Choose the correct URL to access your platform API
- Make sure that you have the privilege required to use an endpoint
- Generate an API token
- Find your client ID
API URL Structure
The platform instance where your client is located determines the endpoint URL structure. All URLs start with the root https://{platformId}.risksense.com/api/v1.
Replace {platformID} with the platform ID for your client. For example, users on https://platform-eu.risksense.com would visit https://platform-eu.risksense.com/doc/
Required Permissions
The Ivanti Neurons for RBVM/ASOC platform supports a privilege-based permissions structure. When the requesting user doesn't have permission to access an endpoint, the API will return a 419 error code.
{ "timestamp": "2021-03-30T16:47:30.648",
"status": 419,
"error": "InsufficientPrivileges",
"clientsMissingPrivileges": [ 656 ],
"missingPrivilege": "Assessment Control",
"method": "PUT",
"path": "/api/v1/client/656/assessment/12" }In the above example, the requesting user was denied access because they lacked the Assessment Control privilege. To overcome this, the requesting user needs to be assigned a role that grants the Assessment Control privilege.
For more information on how to find a role that bestows a specific privilege, visit the article on navigating roles and privileges.
Generating an API Token
In order to use the Ivanti Neurons for RBVM/ASOC API, you will need an API authorization token. Authorization tokens are generated in the Ivanti Neurons for RBVM/ASOC platform. Permissions to access Ivanti Neurons for RBVM/ASOC platform data are based on the permissions of the Ivanti Neurons for RBVM/ASOC user that generates the token.
The following steps will show you how to generate and manage API tokens.
Navigate to your platform instance and log in. Once logged in, click your initials in the top-right corner of the screen and select User Settings.
Once on the User Settings page, scroll down to the API Tokens section. This is where you can generate new tokens to use the Ivanti Neurons for RBVM/ASOC.
If you have already created API tokens in the past, their names are displayed here. You can rename or delete existing API tokens here, as well.
To generate a new token, click the blue Generate button in the API Tokens section.
When you click the Generate button, the following dialog box appears.
Token names may not contain spaces but may contain all alphanumeric characters and the following special characters:
- ^
- \
- -
- ,
- +
- $
After entering your token name, click Generate. Ivanti Neurons for RBVM/ASOC displays the following dialog box showing the newly generated API token.
This token will only be displayed once. Select and copy the API token to a secure location, so you can retrieve it later. Clicking the Clipboard icon to the right of the API token also copies the token to the clipboard as well.
After copying the new token, click OK to return to the User Settings page. This token can now be used to interact with the Ivanti Neurons for RBVM/ASOC REST API.
Finding Your Client ID
Most API requests require a client ID. The Knowledge Base has an article on finding your client ID through the platform UI. You can also retrieve the list of clients to which you are assigned through the endpoint https://{platformID}.risksense.com/api/v1/client.
Visit https://{platformID}.risksense.com/doc/ to try out this endpoint. After logging into the platform, open up the API documentation in a separate window.
Scroll down to endpoints listed under the client topic. Provide the size (the number of results to include in the search query). Set page to 0. Then click the Execute button.
Once execution finishes, you can view a sample CURL command based on your recent search query.
Finally, you can review the response code and the response.
