Introduction to API

Getting Started with API

Complete the full API set up in KaiNexus, including making an API Role, finding unique IDs used in calls, and creating API Keys

Before you can make your first API call, you must complete a few set up tasks in KaiNexus first.

  1. Create an API Role and assign it to users
  2. Create an API Key
  3. Find IDs for data referenced in your calls

Two Line OfieREQUIRED: Your organization must have the API Module enabled to perform the actions mentioned in this article. Reach out to your Customer Success Manager if you're interested in this module.

Create and grant an API Role

To use API with KaiNexus, at least one person in your organization must have the API Administrator Permission. The API Administrator Permission grants the ability to generate and view API Keys, the authentication method for each API request. 

Although this permission can be added to any System Role, we recommend creating a new System Role called "API Admin" that includes the API Administrator Permission. This allows you to only grant the API Administrator Permission to users who will be configuring Boards with API information or generating API Keys.  

After the System Role is created, assign it to any users who will be working with API calls. In the People Section or User Management Administration Page: 

  • Hover over the user to whom you want to add the Role and click the pencil icon.
  • Select the plus icon in the top right corner of the “Roles” section. Select your API Role in the resulting drop-down menu.
  • Select Save.

Ofie Profile PicPro Tip: To grant a System Role to another user, you must have the Local or Global User Administrator System Role permission and have the API Administrator Role as one of your grantable Roles. To learn more about System Role Permissions, check out this article

When you give a user a new System Role such as the API Role, they must sign out and back into the system before the change takes effect. 

Create an API Key

All API calls must be authenticated with a valid API Key generated in KaiNexus. 

What is an API Key?

API Keys are the authentication method for KaiNexus API calls. They are sensitive information and should be treated with the same security as a password. 

API Keys are generated in KaiNexus, and similar to KaiNexus users, they will have a Network Location and a System Role

The Network Location and System Role will determine what data the API Key has permission to access in KaiNexus. If the API Key does not have permission to view an Item, the Item will not be included in the API call, even if it meets the filter requirements of your List. 

Ofie Profile PicExample: If an API Key has a Network Location of “Finance” and a Role that only allows users to view in Items in their own Location, then that particular API Key could only be used to pull data for the “Finance” Location. 

If your organization does not have restrictions surrounding which data should be accessible in API calls, then you can create one API Key with access to all Items. However, if your organization has restrictions, then you can create multiple API Keys, each with access to a different set of data. 

Ofie Profile PicPro Tip: If you receive an error while making an API call, always check to make sure the API Key has the necessary permissions to interact with the data. 

Create a new API Key

You can decide whether you want to grant your IT Team–or whoever will be using the API–access to KaiNexus so that they can generate their own API Keys, or, you can provide the API Key to them. 

To create a new API Key:

  • Navigate to Admin > System > API Keys.
  • Select + Create API Key.
  • In the New API Key window:New API Key
    • Name: Give the API Key a name. 
    • Network Location: Assign at least one Network Location to the API Key. 
    • Roles: Select the + button to assign a Role to the API Key. 
  • Select Save, and it will be added to the list of existing API Keys. 

Ofie Profile PicWarning: You must have the API Administrator Permission to generate new API Keys. If you haven’t logged out since being granted the API Admin Role, sign out then back in. Otherwise, you will not see the API Keys admin page. 

To retrieve an API Key:

  • Navigate to Admin > System > API Keys.
  • Locate the Key you want from the list.
  • Under the “API Key” column, you’ll see a list of symbols. This is not the key. Select the string of symbols, and a window containing the real API Key will appear.
  • Select Copy and save the API Key somewhere secure for later use.

Find IDs for data referenced in your API calls

To make an API call, you will often need to know the ID, or unique identifier, of the data you are exporting or updating.

What is an ID? 

An ID is a way to uniquely identify Items, People, Locations, and other elements in KaiNexus. This unique identifier is used in API calls, telling the system which data to export or update. 

Ofie Profile PicPro Tip: If you are using Network, Attribute Value, or Impact Value API, then you can find Network, Attribute Value, and Impact Value IDs in the Admin section. 

How to find Item and People List IDs

If you are using Item, Chart, or People API, we recommend creating a Board with Item List or People List Cards containing all the data you want to reference in API calls. 

These Cards will have an ID that anyone with API Administrator permission can view, helping you keep all the data you'll need for API calls in one convenient location. 

To find an Item List or People List ID: 

  • Navigate to a Board that contains data to be referenced in API calls. 
  • Hover over a Card header. A tooltip will appear containing the Card’s full title and its ID number.List ID

You can also reference an Item List in your API calls using the Items section of KaiNexus by making a Custom Item List.

Whether your List is saved as a Custom List or added as an Item List Card to a Board, you can reference it in your API calls using the ID. However, we recommend using Item Lists Cards for the visual ease of managing your data. 

If you choose to create a Board that houses Lists referenced in your API calls, then we recommend restricting the Board so that it is only accessible by the people working with API, preventing other users from seeing the Board and cluttering their experience. 

Ofie Profile PicImportant: For more information on creating a new Board, check out this support page . For more information on creating a new Card on an existing Board, check out this support page.

Next article in series:

When you are finished with all the API set up within KaiNexus, you can move to your API application of choice to start making API calls.