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.
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:
- The Super User or a user with the SuperRole enables API key generation for a user or a group of users.
- The developer user generates an API key.
- The developer user (or application), applying the API key, requests the access and refresh tokens from the token creation endpoint.
- The developer user (or application) accesses other desired endpoints, such as an insight query, using the temporary access token.
- When the access token expires, the developer user (or application) periodically requests new access and refresh tokens from the token refresh endpoint.
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.
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
- Enable API Key generation by user groups
- Enable API Key generation for individual users
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.
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.
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
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:
- Configurations
- Get SQLi Connection: This endpoint is available on cloud deployments only.
- Dashboard Schedulers
- Dashboards
- Query
- Schema
- Tokens
- Users