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

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.

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. 

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. 

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:. 
  • 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. 

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. 

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.

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. 

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. 

• Generating API Calls