Using PI API Keys in MagicTools

Guidelines for deciding how to use PI API Keys to access data via MagicTools – for PI

MagicTools – for PI gains access to your organization’s PI data by using an API (Application Programming Interface) Key.

An API Key is always generated in connection with a specific PI User account:

  • The actions taken within MagicTools using an API Key are dependent on the permissions granted to the PI User who “owns” the API Key.
  • All actions taken via MagicTools will be attributed to that PI User in the PI software.

Therefore, when deciding which PI User should own the API Key you’ll use with MagicTools, consider the following:

Current User vs. New User

  1. It may be best to use your own existing PI User account to generate your API Key if you want all actions you take with MagicTools to be attributed to you. With this approach, the actions you take while logged in directly to PI and those taken through MagicTools cannot be distinguished from each other when viewed in the PI software.
  2. It may be best to create a new PI User that you intend to use only with MagicTools so that you can tell the difference between actions taken while signed into the PI software directly and those taken via the PI API and MagicTools. You might put the term “API” or “MagicTools” into the name of the user you create for this purpose.

User Role

  1. If the API Key belongs to an Account Owner or Account Admin user, MagicTools will have access to all person and assessment* data in your PI instance and to perform any actions on that data that are possible via the API.
  2. If the API Key belongs to a Power User, User, or Read-Only user who has access to only some of the person and assessment* data, MagicTools will only be able to read or modify the permission-controlled set of person and assessment data available to that user.

*Note on Cognitive Data: Keep in mind that access to Cognitive Assessment Data requires separate access to be granted if you intend to allow a user this permission. Warning: If you use MagicTools Clean features on PI data that includes Cognitive data, but the user owning the API Key doesn’t have access to Cognitive data, MagicTools will NOT protect your Cognitive data from unwanted removal. MagicTools can only protect data it knows about. If you have Cognitive data, be sure your MagicTools API Key’s user has access to it.

Generating an API Key

Activate API Access – Your organization’s PI instance must have API Access turned on before any API Key you generate will work. Contact Predictive Index Support and ask them “Please ensure that API Access is turned on for our PI organization”.

Where – API Keys are generated in the PI Software’s Administration > User Management area. This administrative action can be taken only by PI Users with the role of Account Admin or Account Owner.

How – Follow the instructions in the following PI Support site to generate an API Key: Integration Guide > Generate an API Key.

Example – Steps to take if you decide to create a new user named Data Manager to own an API Key for use with MagicTools:

  1. Log into PI (https://app.predictiveindex.com) as an Account Admin or Account Owner user with whatever email and password you normally use
  2. Go to Administration (on the menu seen when you click your name in the upper right corner)
  3. In User Management, click “Create New User”
  4. Give the user the following details:
    1. First Name: Data
    2. Last Name: Manager
    3. Email: data.manager@yourdomain.com (You can make up any unique fake email address if it will never be used to log into PI directly and will only ever use the API Key to access PI data)
    4. Job Title: MagicTools Connection
    5. Default Folder: \Your Company (type the backslash and then choose the first item shown in the suggestion list)
    6. Role: Account Admin (this elevated role allows MagicTools to do things like archive unwanted data and move people to new folders)
  5. Click “Create User”
  6. Click on the name of this new user in the list of users so you can view the user details again
  7. At the bottom, you will see a new “API Key” field that wasn’t there before. Click the “Generate New Key” button to the right of that. 
  8. Click the little icon next to the API Key field to copy the new API Key to the clipboard
  9. Click “Cancel” if the Save Changes button is disabled — newly generated API Keys are automatically saved, so there is no need to click Save Changes if generating an API Key is the only action taken.

Sharing an API Key with others

Because API Keys grant powerful access to semi-sensitive information, take precautions to protect them. Some choices:

  • Gmail offers a “Confidential mode” feature (looks like a lock icon in the message toolbar) to send messages securely
  • Use a temporary encrypted sharing tool like the one described here: Securely Share Sensitive Content