1. Cloud
  2. Guides
  3. Tours
  4. Concepts
  5. Tools
  6. References
    1. Built-in Functions
    2. Incorta Component SDK
    3. Incorta Connector SDK
    4. Connectors
    5. Public API
      1. API v1
      2. API v2 (2023.4.0+)
    6. Security
    7. Visualizations
    8. SQL Interface
    9. Other
  7. Integrations
  8. Data applications
  9. Releases

References → Public API v1

Overview

The first version of Incorta public API (Public API v1) is available in all cloud releases. This version isn't compatible with the new authentication introduced in 2023.4.0. Thus, you can't use the 2023.4.0 release to generate new API keys or renew existing ones that are used in Public API v1. However, you can refresh existing access tokens, or you can use the latest API key that you generated before upgrading to 2023.4.0 or later releases and use it to create new access tokens for Public API v1 as usual.

Note

This document is dedicated to users who use an Incorta Cloud release before 2023.4.0. For details on how to have access to Incorta public API on 2023.4.0 and later releases, refer to References → Public API v2.

This document assumes that the developer user has a general understanding of RESTful APIs and how to access the public API endpoints.

Acquiring public API access

The following is an outline of the steps required to get started with Public API v1:

Enable API key generation

As the Incorta Super User or a user with the SuperRole, you enable the users' ability to generate their own API key on an individual basis. API Keys don't 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 to receive an email notification.

Note

Any user or user group with the SuperRole will always have the ability to generate an API key. This functionality can't be disabled.

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

Enable API key generation for multiple users

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

  • As an Incorta Super User or a user with the SuperRole, sign in to 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.

Enable API Key generation by user groups

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

  • As an Incorta Super User or a user with the SuperRole, sign in to 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.

Enable API Key generation for individual users

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

  • As an Incorta Super User or a user with the SuperRole, sign in to 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 drawer, select the Security tab.
  • In the Developer Tool section, toggle Enable API Key Generation.

Create an API key

As a developer user, once you have API key generation enabled for your user account, you can create an API key. API keys identify and authenticate the corresponding user account when making API requests for access tokens.

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

  • As the user that wants to generate an API key, sign in to 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 drawer, 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.

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

  • As the user that wants to renew an API key, sign in to 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 drawer, select the Security tab.
  • In the API Key section, select Renew Key.

Public API v1 endpoints

The first function of the public API is to generate and refresh your access tokens. These tokens have an expiration time 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 Incorta. 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 and 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:

https://<cluster_URL>/incorta/api
Note

You must use the HTTPS scheme to be able to successfully run the API endpoints.

The following are the available endpoints in Public API v1: