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. This includes:
- Making an API Role and assigning it to users
- Finding the ID for the Items, Locations, or People referenced in your calls
- Creating API Keys
REQUIRED: Your organization must have the API Module to perform the actions mentioned in this article.
API Role Setup
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.
Once the System Role is created, assign it to any users who will be working with API calls:
- Select “People” on the left navigation bar
- 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.
To grant a System Role to another user, you must have the appropriate User Administrator Permission and add the new API Admin System 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 they see the changes.
Finding the ID for People, Locations, and Items
To export or update information in an Item List or People List using API, you need to know the List's ID, or unique identifier.
What is an Item List ID?
An ID is a way to uniquely identify an Item, Item List, Network, Person, or People List in KaiNexus. This unique identifier is used in API calls, telling the system which List to export or update.
Each Item List Card and Item List has a unique identifying number that anyone with the API Administrator Permission can access.
Find the Item List ID
We recommend creating a Board with Item List or People List Cards containing the data you want to reference in API calls. This allows you to easily reference all the IDs you need for API in one convenient place.- Item List Cards allow you to filter the data in KaiNexus and display only your specified Items in a List. People Lists Cards work the same but with filters that narrow down users in the system.
- To view the unique identifying number, hover over the Card header. A tooltip will appear containing the Card’s full title and its ID number.
/API/List%20ID.jpeg?width=400&height=368&name=List%20ID.jpeg)
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/Ofie%20Profile%20Pic.png?width=50&height=50&name=Ofie%20Profile%20Pic.png)
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.
Generating API Keys
All API calls must be authenticated with a valid API Key generated in KaiNexus.
What is an API Key?
API Keys are an authentication method generated within KaiNexus to validate API calls. An API Key is like a KaiNexus user in that it will have Network Locations and System Roles assigned to it.
An API Key’s Network Location and Role will determine what information the API Key can access when it pulls data from KaiNexus. If the API Key cannot access an Item that meets the filter requirements of the List it is exporting or updating, that Item will not be included in the call.
- For example, 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 Key could only be used to pull data for the “Finance” Location.
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.
An API Key is sensitive information and should be treated with the same security as a password.
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 generate a new API Key:
/API/New%20API%20Key.jpeg?width=650&height=286&name=New%20API%20Key.jpeg)
- Navigate to Admin > System > API Keys
- Select + Create API Key
- Name the API Key
- Assign at least one Network Location and Role for the API Key
- Select Save, and it will be added to the list of existing API Keys.
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:
/API/API%20Keys.jpeg?width=650&height=133&name=API%20Keys.jpeg)
- 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.
When you have created an API Admin Role, have the List ID for the data you want to reference, and generated at least one API Key, you can move onto Generating API Calls.
Next article in series:
Now that 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.