Tools → Public API

Incorta’s public application programming interface (API) allows developers to interact with data within Incorta for programmatic uses. The power of being able to access data programmatically opens the door to many new application uses. Incorta receives API endpoint request payloads and returns response payloads in JSON.

Overview

Incorta Super User: This document details the steps to enable/disable public API access.

Developer User: This document assumes the developer user has a general understanding of RESTful APIs and describes how to access the Incorta public API endpoints.

Following is a procedural outline of getting started with Incorta public API:

The Super User enables user API key generation.
The user generates an API key.
The user (or application), applying the API key, requests the access and refresh tokens from the token creation endpoint.
The user (or application) accesses other desired endpoints, such as an insight query, using the temporary access token.
When the access token expires, the user (or application) periodically requests new access and refresh tokens from the token refresh endpoint.

Acquiring Public API Access

In order to access the Incorta API, you will need to have an API Key generated for your corresponding user account within Incorta. Your Incorta Super User will need to enable your user account’s ability to generate API keys.

Enable API Key Generation

As the Incorta Super User, you enable the user’s ability to generate their own API key on an individual basis. API Keys do not have an expiration period.

Once a user has received access to generate an API key, they will receive an email notification at the corresponding user email. The user account will need to have logged in at least once in order to receive an email notification.

Note

Any user or user group with the Super User role will always have the ability to generate an API key. This functionality can not be disabled.

The following are three methods available for enabling API Key generation:

Steps to enable API key generation for multiple users

Here are the steps to enable API key generation for multiple users:

As an Incorta Super User, sign into the Incorta Direct Data Platform™.
In the Navigation bar, select Security.
In the Action bar, select Users.
Select the checkbox next to each user for which you would like to enable API key generation.
From the more option menu (kebab icon), select Enable API Key Generation.

Steps to enable API Key generation by user groups

Here are the steps to enable API key generation for user groups:

As an Incorta Super User, sign into the Incorta Direct Data Platform™.
In the Navigation bar, select Security.
In the Action bar, select Groups.
Select the checkbox next to each group for which you would like to enable API key generation.
From the more option menu (kebab icon), select Enable API Key Generation.

Steps to enable API Key generation for individual users

Here are the steps to enable API key generation for individual users:

As an Incorta Super User, sign into the Incorta Direct Data Platform™.
In the Navigation bar, select Security.
In the Action bar, select Users.
Select the checkbox next to the user for which you would like to enable API key generation.
Select Edit (pen icon) in the upper right corner of the Security page.
In the Edit User window, select the Security tab.
In the Developer Tool section, toggle Enable API Key Generation.

Create an API Key

Once you have API key generation enabled for your user account, you may create an API key. API keys identify and authenticate the corresponding user account when making API requests for access tokens.

Steps to creating an API key

Here are the steps for a user to create or renew an API key:

As the user that wants to generate their API key, sign into the Incorta Direct Data Platform™.
Select profile (person icon) in the top right corner of the Navigation bar.
Select your username to open your profile.
In the Edit User window, select the Security tab.
In the API Key section, select Generate Key.

Renew an API Key

If you need to renew an API key, you can renew it from the same location you generated your first API key from. When you renew an API key, the prior key will be invalidated immediately.

Important

Any program using the prior API key will need to be updated with the new API key to maintain functionality.

Steps to renew an API key

Here are the steps for a user to renew an API key:

As the user that wants to renew their API key, sign into the Incorta Direct Data Platform™.
Select profile (person icon) in the top right corner of the Navigation bar.
Select your username to open your profile.
In the Edit User window, select the Security tab.
In the API Key section, select Renew Key.

Public API Endpoints

The first function of the public API is to generate your access and refresh tokens. These tokens have an expiration and are refreshed through an endpoint request. Once you generate your access and refresh tokens, you can use the other API endpoints to request data from dashboards. Your level of data access through the API is determined by the user account that generated the API key.

Note

All Incorta API endpoint’s timestamp values in both request or response payloads use the unix epoch timestamp in milliseconds.

You can access the Incorta public API user interface for your Incorta instance at the following URL:

http://<server address>:<port>/incorta/api

Token creation endpoint

When requesting your initial access and refresh tokens, you will access the /tokens endpoint with a POST request. Access tokens allow request access to other API endpoints. A refresh token is paired with your access token, and is used in the /refresh endpoint to obtain new access and refresh tokens. Subsequent requests for a refreshed access token will use the /refresh endpoint.

Important

Access tokens have a ten minute expiration and refresh tokens have a thirty minute expiration.

Token creation: Endpoint URL

Following is the URL to call the /tokens endpoint.

http://<server address>:<port>/incorta/api/v1/tokens

Token creation: Request

Following is a json template of a /tokens endpoint request:

{
  "tenantName": "string",
  "loginName": "string",
  "requestHash": "string",
  "timestamp": number
}

tenantName: String value of the user’s tenant

loginName: String value of the user login name.

requestHash: A concatenated hex string, using the sha256 hashing algorithm, of the API Key and the request epoch timestamp in milliseconds.

timestamp: The request epoch timestamp in milliseconds

Note

The loginName value is the user login name and not the user display name.

Important

By default, there is a 30 minute valid window between the request timestamp and the receiving endpoint timestamp. You can configure the valid request duration in the internal configurations, “public.apis.tokens.request.duration”.

Creating a requestHash and timestamp

The following are simple example code snippets for creating your timestamp and requestHash values. Be aware that the syntax and methods used may vary depending on your language version.

Python version: 3.5

import hashlib
import time
import calendar
# Create the epoch millisecond timestamp
timestamp = calendar.timegm(time.gmtime()) * 1000

# Enter the user API key as a string
api_key = "<Your API key>"

# Concatenate the api_key and timestamp strings
request = (api_key + str(timestamp)).encode('utf-8')

# Generate the request hash string
request_hash = hashlib.sha256(request).hexdigest()

print (f"The epoch timestamp in milliseconds is: {timestamp}")
print ("The sha256 request hash is: " + request_hash)

Javascript version ES8

async function digestMessage(message) {
    // Encode as UTF-8
    const msgBuffer = new TextEncoder().encode(message);                    

    // Hash the message
    const hashBuffer = await crypto.subtle.digest('SHA-256', msgBuffer);

    // Convert ArrayBuffer to Array
    const hashArray = Array.from(new Uint8Array(hashBuffer));

    // Convert bytes to hex string                  
    const hashHex = hashArray.map(b => ('00' + b.toString(16)).slice(-2)).join('');
    console.log("The request hash is: " + hashHex);
}

// Create timestamp
const timestamp = Date.now();
// The user API key as string
const api_key = "<Your API Key>";
// Concatenate the api_key and timestamp
const request = api_key + timestamp;

console.log( "The epoch timestamp in milliseconds is: " + timestamp );
digestMessage(request);

Java version 11

import java.time.Instant;
import java.security.MessageDigest;

public class Main {
    public static void main(String args[]) {
        // Create the epoch timestamp string in milliseconds
        String timestamp = Long.toString(Instant.now().toEpochMilli());
        System.out.println("The epoch timestamp is: " + timestamp);


        // The user API key as a string
        String api_key = "<Your API Key>";
        // Concatenate the api_key and timestamp strings
        String request = api_key + timestamp;


        // Generate the requestHash string
        String request_hash = sha256(request);  

        System.out.println(request_hash);
  }

    // Sha256 hashing function
    public static String sha256(String base) {
    try{
        MessageDigest digest = MessageDigest.getInstance("SHA-256");
        byte[] hash = digest.digest(base.getBytes("UTF-8"));
        StringBuffer hexString = new StringBuffer();

        for (int i = 0; i < hash.length; i++) {
            String hex = Integer.toHexString(0xff & hash[i]);
            if(hex.length() == 1) hexString.append('0');
            hexString.append(hex);
        }

        return hexString.toString();
    } catch(Exception ex){
       throw new RuntimeException(ex);
    }
}
}

Recommendation

In this Java example, we provide a hashing function for ease of use. As a best practice you can use a public library such as the Apache Commons Codec or Guava: Google Core Libraries for your hashing function.

C# version: 4.0

using System;
using System.Security.Cryptography;
using System.Text;

public class Program {
    public static void Main(string[] args) {
        // Get the current timestamp
        DateTimeOffset now = DateTimeOffset.UtcNow;

        // Convert the timestamp to Unix epoch in milliseconds
        string timestamp = now.ToUnixTimeMilliseconds().ToString();
        Console.WriteLine("The epoch timestamp is: " + timestamp);

        // The user API key as a string
        string api_key = "<Your API Key>";

        // Concatenate the api_key and timestamp strings
        string request = api_key + timestamp;


       // Generate the request hash string
       using (SHA256 sha256Hash = SHA256.Create())
        {
            string hash = GetHash(sha256Hash, request);
            Console.WriteLine("The SHA256 request hash is: " + hash);
        }


    }


    private static string GetHash(HashAlgorithm hashAlgorithm, string input)
    {

        // Convert the input string to a byte array and compute the hash.
        byte[] data = hashAlgorithm.ComputeHash(Encoding.UTF8.GetBytes(input));

        // Create a new Stringbuilder to collect the bytes
        // and create a string.
        var sBuilder = new StringBuilder();

        // Loop through each byte of the hashed data
        // and format each one as a hexadecimal string.
        for (int i = 0; i < data.Length; i++)
        {
            sBuilder.Append(data[i].ToString("x2"));
        }

        // Return the hexadecimal string.
        return sBuilder.ToString();
    }
}

Request hash alternatives

Instead of using a programmatic solution to generate your request hash, you can use resources available online. A site such as currentmillis can be used to get your current timestamp in milliseconds. A hash converter such as emn178.github.io can be used to encode your API key and timestamp. Any generated request hash will always expire 30 minutes after being generated.

Token creation: Response

The /tokens endpoint has five possible response codes and payloads.

Code	Description	Payload Response
201	Created	See Token creation: 201 Response
400	Bad Request	`{"message": "string"}`
401	Unauthorized	`{"message": "string"}`
404	Not Found	`{"message": "string"}`
500	Internal Server Error	`{"message": "string"}`

Token creation: 201 Response

{
  "accessToken": "string",  
  "refreshToken": "string",
  "type": "string",  
  "accessTokenExpiresAt": number,  
  "refreshTokenExpiresAt": number
}

Note

The expire values are in unix epoch time in milliseconds.

Token refresh endpoint

Once your access token expires you will need to use the /refresh endpoint to request new tokens. The /refresh endpoint is accessed with a POST request. When you request tokens from the /refresh endpoint, the prior access token and refresh token will be invalidated. If both the access token and refresh token have expired before your next /refresh request, you will need to request tokens from the /tokens endpoint.

Important

Access tokens have a ten minute expiration and refresh tokens have a thirty minute expiration.

Token refresh: Endpoint URL

Following is the URL to call the /refresh endpoint.

http://<server address>:<port>/incorta/api/v1/tokens/refresh

Token refresh: Request

Following is a JSON template of a /refresh endpoint request:

{
  "accessToken": "string",
  "refreshToken": "string"
}

accessToken: String value of the access token provided in /tokens endpoint.

refreshToken: String value of the refresh token provided in the /tokens endpoint.

Token refresh: Response

The /refresh endpoint has three possible response codes and payloads.

Code	Description	Payload Response
201	Created	See Token refresh: 201 Response
401	Unauthorized	`{"message": "string"}`
500	Internal Server Error	`{"message": "string"}`

Token refresh: 201 Response

{
  "accessToken": "string",  
  "refreshToken": "string",  
  "type": "string",  
  "accessTokenExpiresAt": number,  
  "refreshTokenExpiresAt": number
}

Note

The expire values are in unix epoch time in milliseconds.

Dashboard prompts endpoint

The /prompts endpoint will return a list of all prompts and presentation variables in a requested dashboard. If the dashboard does not contain prompts or presentation variables, the /prompts endpoint will return a list of the dashboard’s dimension values. The /prompts endpoint is accessed with a GET request.

Header requirements

In the request header you will need to include your access token with a type of Bearer. Following is an example of the authorization line required in the request header:

Authorization: "Bearer <Access Token>"

Dashboard prompts: Endpoint URL

Following is the URL to call the /prompts endpoint.

http://<server address>:<port>/incorta/api/v1/dashboards/<dashboardGuid>/prompts

The dashboardGuid is located in the URL of the desired dashboard. It is required in the /prompts endpoint URL. The following are instructions on where to locate the dashboardGuid:

As the user that wants to access the public API of a dashboard, sign into the Incorta Direct Data Platform™.
In the navigation bar, select Content.
Select the desired dashboard.
In your browser URL, locate the dashboardGuid in the URL.

Following is an example of where to locate the dashboardGuid in a dashboard URL:

http://<server address>:<port>/incorta/#/dashboard/<dashboardGuid>

Dashboard prompts: Request

The /prompts endpoint does not require any request payload. The required information for the endpoint, the access token and dasboardGuid is located in the header and URL path.

Dashboard prompts: Response

The /prompts endpoint has three possible response codes and payloads.

Code	Description	Payload Response
200	OK	See Dashboard prompts: 200 Response
404	Not Found - dashboard does not exist.	`{"message": "string"}`
500	Internal Server Error	`{"message": "string"}`

Dashboard prompts: 200 Response

{
  "prompts": [    
    {
      "dataType": "string",      
      "field": "string",      
      "function": "string",      
      "label": "string",      
      "operator": "string",      
      "defaultValues": [        
        "string"      
      ],      
      "values": [        
        "string"      
      ],      
      "variable": "string"    
    }  
  ]
}

Insight query endpoint

The /query endpoint will return the data from a specified insight on a dashboard. You can optionally include prompts in your request payload to filter your results. You may also request the result data based on a different specified user. The /query endpoint is accessed with a POST request.

Header requirements

In the request header you will need to include your access token with a type of Bearer. Following is an example of the authorization line required in the request header:

Authorization: "Bearer <Access Token>"

Insight query: Endpoint URL

Following is the URL to call the /query endpoint.

http://<server address>:<port>/incorta/api/v1/dashboards/<dashboardGuid>/insights/<insightGuid>/query

The dashboardGuid and insightGuid are located in the URL of the desired dashboard insight. They are required in the /query endpoint URL. The following are instructions on where to locate the dashboardGuid and insightGuid:

As the user that wants to access the public API of a dashboard, sign into the Incorta Direct Data Platform™.
In the navigation bar, select Content.
Select the desired dashboard.
In the top right corner of the desired insight, select focus (expand arrows icon).
In your browser URL, locate the dashboardGuid and insightGuid in the URL.

Following is an example of where to locate the dashboardGuid and insightGuid in a dashboard URL:

http://<server address>:<port>/incorta/#/dashboard/<dashboardGuid>/tab/<tabGuid>/insight/<insightGuid>

Insight query: Request

The /query endpoint will accept an optional JSON payload that can be used to filter the response data. Following is an example /query request payload with descriptions of each field:

{
  "prompts": [
    {
      "field": "string",
      "operator": "string",
      "values": [
        "string"
      ],
      "options": {
        "caseSensitive": true
      },
      "type": "string",
      "variable": "string"
    }
  ],
  "pagination": {
    "startRow": number,
    "pageSize": number
  },
  "username": "base64.encode(loginName)"
}

prompts: An optional array of objects to add prompts to your query.

field: A string value containing the absolute path of the table column (the fully qualified name of the column: schemaName.tableName.columnName) filtered by the prompt.
operator: A string value of the prompt’s operator; e.g. =, >, <.
values: An array of string values containing the filter values.
options: An object for specific features of prompt.
- caseSensitive: A boolean value if the prompt is case-sensitive. This option applies to the following operators only: CONTAINS, NOT_CONTAINS, STARTS_WITH, NOT_STARTS_WITH, and ENDS_WITH. For other operators, the value is always case-sensitive.
type: A string value prompt type. String value must be either “dimension” or “variable”.
variable: A string value of the prompt’s variable name.

pagination: An optional object to add pagination to your query.

startRow: An integer value of the starting row for pagination.
pageSize: An integer value of the number of rows per page.

username: An optional string value, encoded in base64, to have your query processed as another user.

Username field

The username optional field can only be used by a user with the Super User role. When you apply the username field, the query will be processed as if the request is from the specified user. The username in this field must be a different user than the user account associated with your API key. From your terminal, the following code example can be used to generate the base64 encoded username:

echo -n '<loginname>' | base64

Insight query: Response

The /query endpoint has five possible response codes and payloads.

Code	Description	Payload Response
200	OK	See Insight query: 200 Response
400	Bad Request	`{"message": "string"}`
404	Not Found	`{"message": "string"}`
422	Unprocessable Entity	`{"message": "string"}`
500	Internal Server Error	`{"message": "string"}`

Insight query: 200 Response

{
  "headers":{
    "dimensions": [
      {
        "columnName": "string",
        "dataType": "string",
        "label": "string",
        "type": "string",
        "index": number
      }
    ],
    "measures": [      
      {
        "columnName": "string",
        "dataType": "string",
        "label": "string",
        "index": number,        
        "grandTotal": "string"
      }
    ],
    "apiVersion": number,
    "totalRows": number
  },  
  "data": "string",
  "links": "string",
  "conditionalFormatting": "string"
}