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 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: Keep in mind that access to Cognitive Assessment Data requires separate access to be granted if you intend to allow a user this permission.

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.

Sharing an API Key with others

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

One way to securely share an API Key is to use a temporary encrypted sharing tool like the one described here: Securely Share Sensitive Content