Who is this article for?

Users who want to learn more about the application API.

User account with API access is required.

An Application Programming Interface (API) allows applications to interact with a service or platform through a set of protocols and instructions. Users can leverage APIs to integrate external data and functionality into their own applications or systems by calling the API and sending and receiving information programmatically. This article will walk you through what the Ideagen Risk Management offers.

In this article:

1. Overview
2. Uses for the API
3. Features available through the API
4. Connecting with other systems
5. Accessing the API
6. Obtaining an authentication token
7. Available endpoints
8. Request Rate Limit
9. Further reading

1. Overview

Ideagen Risk Management provides customers limited access to their data via a REST-ful API. The API does not provide direct database access – the same business rules found in the Browser and Classic interfaces also apply to the API, and the same rules of ownership and permission apply.

Provision of an API enables Ideagen Risk Management customers to use their data in third party systems such as a BI (business intelligence) reporting tool. Access to the API is provided as is.

Customers will need to provide their own connector software to be able to successfully connect Ideagen Risk Management to any third-party system.

2. Uses for API

That depends on the needs and requirements of your organisation.

Some examples include:

• Using Ideagen Risk Management to perform risk assessments for your Internal Auditing solution.
• Using Performance Indicator data in BI dashboards.
• Tracking the progress of third-party Actions.
• Providing data for Charts by importing PI data from third-party systems.

3. Features available through the API

We currently offer the following data and functions:

• Performance Indicators
• Actions
• Risks
• Risk Queries
• Feedback items (excluding Contacts)

4. Connecting with other systems

There is no reason that you will not be able to use Ideagen Risk Management data with another system.  owever, you will need to provide a Connector to use Ideagen Risk Management data in a third-party system via the API.

The API only provides access to your data and does not legislate for how it can be used once extracted, nor does it transform or reshape it into something suitable for your intended use case. The responsibility for doing this is yours.

It is common practice to connect to API-ready systems with a Connector: a piece of software that can read from the source system, transform the data it receives as needed, and then write the result into the second system. Connectors can be written to do most tasks, and can operate constantly, to a schedule, or as needed.

5. Accessing the API

The API is available only to users for whom API access is enabled. Any Ideagen Risk Management user account can become API-enabled, but customers should contact Ideagen Risk Management support or their Account Manager and request that this be done. Once enabled, Users are then able to generate their own OAuth2 credentials which can be used to access the API.

Activities undertaken by the API account are recorded in the Audit Trail and can be viewed in the same ways you would see audits for any other user.

Access to the Ideagen Risk Management API is facilitated by OAuth2 authentication through the provided Ideagen Risk Management user account. Users cannot access the API with their conventional username and password but must generate API Credentials from their Ideagen Risk Management profile page.

Make a secure note of these as they cannot be recovered and are not stored for security reasons. Any lost or forgotten credentials will need to be regenerated.

• API Username
  A slightly modified version of the user’s existing name to ensure uniqueness.
• API Password
  A long and randomly generated password.
• Client Name
  A short string to identify the software which will connect to the API.
• Client Secret
  A second long, randomly generated password.

Credentials periodically expire as a further security measure and will need to be regenerated.

6. Obtaining an authentication token

To use the, your credentials must be used to obtain a reusable authentication token (also known as an access token). They are generated once from the credentials supplied to you and are to be used with every subsequent request to the API.

Access tokens are obtained the following ways:

1. Using the supplied credentials with an API tool, such as Postman, to generate an OAuth2 access token.
2. Sending a POST request to the Ideagen Risk Management API yourself using the instructions below.

URL

https://{site}.pentanarpm.uk/cpmweb/oauth/token (UK & EU customers)
or
https://{site}.pentanarpm.us/cpmweb/oauth/token (US customers)

Where {site} is replaced with the hostname you use to access the Ideagen Risk Management Browser interface. Usually this is some form of your organisation’s name.

HTTP Headers

Send the following headers with your POST request for an Access Token…

Accept: application/json
Content-Type: application/x-www-form-urlencoded
Authorization: Basic {client+secret}

…where {client+secret} is replaced with a Base64 encoded concatenation of the Client Name and Client Secret you were provided with a colon delimiter. For instance, the Client Name is likely to be api_client and the Client Password should resemble something like c2eb78ea-3cec-4894-b5f9-62961c298196 so combine these with a colon to get …

api_client:c2eb78ea-3cec-4894-b5f9-62961c298196

You must now Base64[2] encode this string to get the value you should use in your request.

Request Data

Your request body must include the following x-www-form-urlencoded key-value pairs using information from the supplied credentials …

Response

The response’s body will contain a JSON payload. You can find your Access Token within this, in the field called access_token.

7. Available Endpoints

To find the API endpoints, navigate to https://{site}.pentanarpm.uk/cpmweb/swagger-ui.html whilst logged in as an API User.

Pulling notes from the API
There are no API endpoints for notes, therefore it is not possible to pull out notes from the API.

8. Request Rate Limit

Requests made to the API are limited to 600 requests a minute.

9. Further reading

• Querying the Ideagen Risk Management API using Postman