Technical - Setting Up and Maintaining an API Key

Overview

Calling the Kuali APIs requires the use of an API key.  These keys expire on an annual basis and must be regenerated within the system. API keys are linked to a Kuali users, and notifications are sent one month in advance of API key expiration. To avoid the impact of staff turnover, it is recommended that institutions setup a standalone user to maintain these keys with a departmental email associated with the group that maintains their Kuali integrations. These steps should be repeated for all environments and must be completed by a user with Kuali User Admin privileges.

Create a Kuali Research User

The first step is to create a user in the Kuali Research system.  If you already have a hrserviceaccount user set up and you just need to create a new API key you can skip to the Generating the API Key section below.

Navigate to System Admin Portal > System Admin > Identify > Person

Press the create new button in the upper right-hand corner of the screen and complete the following fields on the Person document that displays.

• Description: Enter a description per your institution's naming standards.
• Principle Name: hrserviceaccount
• Active: Leave Checked
• Affiliations Panel: Complete the following fields then click add
  • Affiliation Type: Affiliate
  • Campus Code: Select your Primary Campus Code
  • Default: Leave Checked
• Contact Names Panel: Complete the following fields and then click add
  • Name Code: Select Primary
  • First Name: HRService
  • Last Name: Account
  • Default: Check
  • Active: Leave Checked
• Email Addresses Panel: Complete the following fields and then click add
  • Email: Enter the email address that should be notified when your API keys are approaching expiration. This email should be available to the whole team that maintains your Kuali Research integration.  Also, this email must be unique and not already in use by another user in the system.
  • Type: Home
  • Default: Leave Checked
  • Active: Leave Checked
• Membership Panel:  add the below roles to the user
  • KC Superuser (Role ID 10079 out of the box)
  • Technical Administrator (Role ID 63 out of the box)

When the above fields are complete, click the submit button at the bottom of the screen.

Navigate to System Admin Portal > System Admin > Miscellaneous > Push Users to the Core Auth Service

When you click the above link the system will display Are you sure you want to push all users to the auth service. Press the Yes button.

When the User push is complete the system will display a message indicating how many users exist in the system, how many were added, modified, and remained unchanged. Once this message loads your HR user has populated your institution's Kuali User table.

Kuali User Setup

Next navigate to https://{Kuali Instance Domain}/users and search for your user by the Principal Name entered above.

Click on the user and click on the Edit button.

Change the Role to Admin.

Enter the password you want for this user. It is recommended that this be a very strong password. This should be kept in an encrypted file that is only available to the technical staff who maintain your Kuali integrations. Then press the Save button.

Generating the API Key

Press the API Keys tab at the top of the hrserviceaccount user's account display.

Press the Create KEY button

Enter a Name for your API Key in the Name field and press Create Key

When you do this the system will display the API key that it generated. This is the only time you can retrieve the key. If you lose it you will need to revoke that key and generate a new one. So copy this key so you can use it to setup your HR feed and other integrations.  This key is used in the XML created/managed by your local IT staff to make the necessary connections to feed from your HR system to Kuali Research.

Once you've generated the new API Key and you have confirmed it's working in the HR feed you will need to remove the old keys that are no longer used by clicking the 'Revoke' key.

When your API keys are a month from expiration the email you have listed in this account will be notified (also any kuali users with the role of 'admin').  Someone from your technical team can go to https://{Instance Domain}/users to find the HR Services user and then from the API tab complete the steps above and generate a new API key to use in your HR feed XML.

The API key is used to setup the HR person feed per the Technical - Configuring HR API article and is necessary for other integrations that use the Kuai Research API.