API tokens are used for several purposes within the Canary system.

• Reading data from the Historian using the Read API
• Writing data to the Historian using the Write API
• Writing data to the Historian from a remote Collector when Tag Security is enabled in the Identity service
• Adding a remote Historian view to a Views service
• Making a secure connection with the ODBC client
• Running Automated Reports from a remote Identity service
• Upgrading a Remote Axiom/Views server from v23

API tokens can be added as needed and used for more than one purpose. For example, if implementing all of the scenarios above, a token can be created for each one, or the same token could be used for all of them (not recommended).

A token is linked to an internal Canary user who is then placed on an access control list (ACL) depending on what the token is used for. This Canary user could be one that is mapped to an external user or it can exist by itself.

The Canary system comes with a few API tokens and their corresponding Canary users already defined:

• Anonymous
• Axiom Report Service Account*
• Installer Migration Service Account*

*These Canary users are used for the last two scenarios listed above respectively. Therein, a new API token does not need to be created for them.

Configuration

1. Open the Canary Admin client and navigate to the Identity tile>Security tab at the bottom.
2. If needing to create a new Canary user to link the token to, select the Users tab on the left. If a Canary user already exists that you wish to link the token to, skip to step 5.
3. Select the ADD button in the Canary Users section.

   

4. Enter an intuitive name for the Canary user. Click ADD then APPLY.

   

5. Select the API Tokens tab on the left and click ADD.

   

6. Provide an intuitive description. Select the Canary user from the drop-down menu and set the Expiration Policy. Click ADD and APPLY.

   

7. Add the Canary user to the appropriate ACL by selecting the Access Control Lists tab on the left or the Tag Security tab if needing to give the user read/write permissions within the data hierarchy. This will vary depending on what the API token is used for. The links at the top of the article will provide more information for each scenario.