References → Public API v2

Overview

The second version of Incorta public API (Public API v2) is available starting the 2023.4.0 release. This release introduces seamless authentication, facilitating the generation of access tokens for Public API v2. The level of data access through the public API is determined by the user account that generated the API access token.

Acquiring public API access

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

• The Super User or a user with the SuperRole enables public API access for a user or a group of users.
• The developer user generates an API access token, whether PAT or OAuth 2.0 JWTs.
• The developer user (or application) accesses the desired endpoints using the generated access token.

Enable public API access

As the Incorta Super User or a user with the SuperRole, you enable the users' ability to access Incorta public API. When granted permission to access the public API, each user 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.

In regard to personal access tokens (PATs), each user can create and maintain up to 10 active access tokens and set an expiration date for each token. The user can also revoke any access token. The user or any third-party application can't use a revoked access token when using the API endpoints.

The following are three methods available for enabling API access:

• Overview
• Acquiring public API access
  • Enable public API access
    • Enable public API access for multiple users
    • Enable public API access by user groups
    • Enable public API access for individual users
  • Create an API access token
    • Create access token using Incorta
    • Create access token using OAuth 2.0
  • Revoke a personal access token
• Public API v2 endpoints

Enable public API access for multiple users

Here are the steps to enable API access 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 public API access.
• From the more option menu (kebab icon), select Enable Public API.

Enable public API access by user groups

Here are the steps to enable public API access 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 public API access.
• From the more option menu (kebab icon), select Enable Public API.

Enable public API access for individual users

Here are the steps to enable public API access 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 public API access.
• 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 Public API.

Create an API access token

There are two ways to acquire an access token, through Incorta personal access token (PAT) and OAuth 2.0.

Create access token using Incorta

As a developer user, once you have public API access enabled for your user account, you can create and maintain up to 10 active access tokens and set an expiration date for each token. API access tokens identify and authenticate the corresponding user account when using the API endpoints.

Here are the steps for a user to create an API access token:

• As the user that wants to generate an API access token, 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 Tokens section, select Create Personal Access Token.
• In the Create New API Token dialog,
• Enter a name for the access token.
• Specify the expiration date. You can select from predefined periods: 7 days, 30 days, or 90 days, or you can select Select expiry date and specify a custom expiry date. You can also set the validity of the access token to Never Expire.
• Select Create.
• Make sure to copy the generated access token and keep it as you can't see it again once you close the dialog.
• Select Close

Create access token using OAuth 2.0

You must enable the OAuth 2.0 for Public APIs Authentication option in the CMC and have your own configured authorization server.

You should still enable the public APIs for the designated users so they can use the APIs.

Use the following steps to configure your authorization server, knowing that each identity provider (IDP) has a different way of configuration:

• Configure Incorta on your IDP (authorization server).

• The following claim must be identified in a generated access token, knowing that namespace is https://incorta.com:

  • namespace/email, where email is the configured loginName of the user

    For example:

    Copy
    exports.onExecutePostLogin = async (event, api) => {
      // This adds the authenticated user's email address to the access token.
      if (event.authorization) {
        const namespace = 'https://incorta.com';
        api.accessToken.setCustomClaim(`${namespace}/email`, event.user.email);
      }
    };
    
    

    Note

    In 2023.4.0 and 2023.4.1 releases, you must identify another claim: namespace/tenant, where tenant is the user tenant name in Incorta.

    For example: api.accessToken.setCustomClaim(`${namespace}/tenant`, 'default');

• Add your configured IDP URL in the CMC after enabling OAuth 2.0 for Public APIs Authentication.

When enabling using OAuth 2.0

It is important to note the following when you enable OAuth 2.0 as your authentication method:

• You can only consume OAuth 2.0 tokens with Public APIs v2.
• Any configured scripts using PAT will not work and you must update your scripts accordingly.

When disabling using OAuth 2.0

It is important to note that when you disable OAuth 2.0, any scripts using PAT keys will behave in their old manner if the PAT has not expired.

Revoke a personal access token

You can revoke any personal access token. When you revoke an access token, you can't undo this action as the access token is removed from the list.

Here are the steps to revoke a personal access token:

• 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 Tokens section, for the row of the access token you want to revoke, select Revoke.
• In the dialog, select Yes, revoke.

Public API v2 endpoints

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

Copy
https://<cluster_URL>/incorta/api?urls.primaryName=v2

The Base URL of all the Public API v2 endpoints is: /incorta/api/v2.

The following are the available endpoints in Public API v2:

• Catalog
  • List Catalog Content
  • List Catalog Folder Content
  • Search Catalog Content
• Configurations
  • Get SQLi Connection. This endpoint is available on cloud deployments only.
• Dashboard Schedulers
  • Schedule Dashboard Report
• Dashboards
  • Dashboard Prompts
  • Insight Query
• Load Plan
  • Execute Load Plan Endpoint
  • Load Plan Execution Status Endpoint
• Query
  • Query a Business View
• Schema
  • Load Schema
  • Schema Status
  • List Schemas
  • List Schema Objects
• Users
  • Reset Passwords
  • Transfer Ownership