Integrate your data with Klarity

Page Sections

Keep all your business-related data in Klarity. Using our External Integrations you can add any external data like licenses or on-prem VMs to Klarity and keep them all in one tool together with the cloud-related data that Klarity provides. You can easily assign that data to your applications, environments, and business contexts to have one source of truth for your business decisions.

Our external integrations will let you add new estate records and allocate them to the applications and environments along with enriching existing estate records by for example backup data from your backup tool.

Basic concepts

you can add any external data to Klarity in a form of estate records
you can enrich existing estate records with related data
to add an External Integration, you use Klarity’s UI or GraphQL API
to carry out actions on your External Integration, you use Klarity's (dedicated) REST External Integrations API

Prerequisites

Before making use of the API, you must first register your External Integration in Klarity, which provides you with the required authentication credentials. Then, you use those credentials to obtain a Token that allows you to make authorized calls to the API.

External integrations

To test the integration not on your production data please use our sandbox. More sandbox related information can be found here: https://docs.klarity.nordcloudapp.com/usage/sandbox/.

Each external integration must provide all the data that Klarity requires in order to handle the Estate Records for that External Integration.

For example, to add a new Estate Record using the API, the Estate Record data can include:

ID (required)
Name
Type (required)
Metadata
Tags
Costs

Accessing the External Integrations API

To make use of the External Integrations API, you require authentication in the form of your External Integration's ID and Secret.

Creating an API Secret

In Klarity, in Main, select External Integrations, and then click Add New Integration. Complete the 2-stage process. When you reach the Summary stage, you are notified that a new External Integration was added. Klarity added your new External Integration by using the token generated from the Secret.

You're not done yet! Make a note of the permanent ID of your new External Integration. Also, note the Secret for that ID. This Secret is shown only once. Before leaving this page, make sure that you copy the Secret to a secure place.

Warning: Do not store the Secret in plain-text where others can access it. Anyone with this Secret can generate a token which provides authentication in relation to your resources. If you feel that the Secret has been compromised, you can re-generate the Secret for a particular ID. Please note that re-generating a new Secret invalidates the previous Secret.

Making authorized calls to the API

To make valid calls to the External Integrations API, you must first generate a JSON Web Token (JWT) for authentication. To generate this token, you must call the identity service, and provide your ID and Secret.

The identity service is: https://identity.nordcloudapp.com

To obtain the JWT token, you must make a POST call to the /oauth/token endpoint with this JSON payload:

{
  "client_id":"$(id)",
  "client_secret":"$(secret)",
  "audience":"https://integrations-api.klarity.nordcloudapp.com",
  "grant_type":"client_credentials"
}

To understand how to generate a JWT Token in your preferred programming language, see the example code snippets in the tabs below:

Curl
Go
Python
TypeScript

curl --request POST \
      --url https://identity.nordcloudapp.com/oauth/token \
      --header 'content-type: application/json' \
      --data '{"client_id":"$id","client_secret":"$secret","audience":"https://integrations-api.klarity.nordcloudapp.com","grant_type":"client_credentials"}'

Using the External Integrations API

This section contains details on:

the API schema in Swagger format
the SDKs generated from the API
calling the API from the SDKs

API schema in Swagger

To view the schema of the External Integrations API in Swagger format, see:

External Integrations API Schema

SDKs generated from API

To view the SDKs for the API, see:

for Go and Python: https://github.com/nordcloud/klarity-integrations-sdk
for TypeScript: https://github.com/nordcloud/klarity-integrations-sdk-node

Using SDKs to call the API

To understand how to call the External Integrations API by using the SDKs, see these examples:

Curl
Go
Python
TypeScript

curl --request POST \
      --url https://integrations-api.klarity.nordcloudapp.com/v1/estateRecords \
      --header 'content-type: application/json' \
      --header 'Authorization: Bearer $token' \
      --data '{
        "records": [
          {
            "id": "js002",
            "name": "Jira Subscription 002",
            "type": "jira/subscription/basic",
            "metadata": {},
            "tags": {
                "key": "key_example"
            }
          }
        ]
      }'

Edit this page on GitHub

Klarity