Skip to content

API Token

Overview

API tokens in Tycho Data Osprey are used to authenticate programmatic access to Osprey allowing external tools like scanners, scripts, or integrations to securely communicate with the Osprey backend.

If you are running a scanner (e.g., PI Data Archive or AF scanner) or performing automated actions via the API, you'll need to generate an API token to authorize these requests.

Why Use an API Token?

You'll need an API token when:

  • Running a scanner outside of the browser (e.g., TychoScanner.exe).

  • Automating interactions with Tycho Data Osprey using scripts or agents.

  • Integrating third-party tools that send data to or retrieve data from Osprey such as the Osprey plugin for PI Vision.

API tokens replace the need for a username and password, and are safer for automated use cases. You can revoke or regenerate them at any time.

How to Generate an API Token

Follow these steps to generate an API token from the Tycho Data user interface:

  1. From the top-right profile dropdown, select Settings.

  2. Navigate to the API Tokens tab.

  3. Click Generate to create a new token.

  4. Give your token a clear name (e.g., PI Scanner Token).

  5. Set the Expiration (days) field:

    • Set to 0 for a non-expiring token.

    • Or provide a specific number of days for time-limited access.

  6. Click Generate and copy the token immediately. You won't be able to view it again. Store the token securely. Treat it like a password.

Using the Token

Once generated, you use the token securely. For instance, if you are configuring a scanner to connect to Osprey:

Set the token as an environment variable in Windows:

  1. Press Windows + S, search for Environment Variables, and open:

    Edit the system environment variables → Click Environment Variables

  2. Under User variables or System variables, click New...

  3. Fill in:

    a. Variable name: TYCHODATA_OSPREY_APITOKEN b. Variable value: your-api-token-here

  4. Click OK to save and exit all dialog boxes.

  5. Restart any Command Prompt, PowerShell, or application that needs the token including Task Scheduler tasks.

You then reference this environment variable in your appsettings.ini file:

tychoDataAPIToken = \${TYCHODATA_OSPREY_APITOKEN}

This allows the scanner to authenticate securely without hardcoding sensitive credentials.