API Authentication and Access

Overview

Before any system can access the TrackVia API, it must authenticate using an API Key and an Auth Token. These credentials verify the caller's identity and enforce the permission level of the associated user account. Together they ensure that API access is granted only to authorized systems, and only to the resources those systems are permitted to access.

This article covers the complete setup process for API authentication in TrackVia: creating a dedicated API User, locating your API Key, and generating Auth Tokens for use in integrations.

⚠ Prerequisites: You must be a TrackVia Super Admin to complete the steps in this article. API Token creation requires at least one active API User to be configured first — complete the steps in order.

Step 1: Create an API User

API Users are a special category of TrackVia user created exclusively for API connections and integrations. You must designate at least one API User before Auth Tokens can be created.

Designating a user as an API User changes their account in the following ways:

Web and mobile access is disabled — API Users cannot log into the TrackVia web or mobile applications. They exist solely for API authentication.
SSO is bypassed — API Users bypass Single Sign-On login to prevent their Auth Tokens from inadvertently expiring due to SSO session policies.
Password expiration is disabled — API Users are exempt from TrackVia's password expiration policies, ensuring integrations are not disrupted by forced password resets.
Auth Token creation is enabled — only accounts designated as API Users can be associated with Auth Tokens.
Role-based permissions still apply — API Users must be assigned to a properly configured role with the appropriate read, write, or delete permissions for the resources the integration needs to access. Follow the principle of least privilege and grant only what the integration requires. See Workato: Best Practices for TrackVia Connections for role configuration guidance.

How to Designate a User as an API User

Navigate to Manage Users in the TrackVia Admin panel
Select the profile of the user you want to designate as an API User
Check the Set As API User checkbox on their profile page
Save the profile

Note: Users in "Unverified" status cannot be designated as API Users. Ensure the user account is active before proceeding.

The Set As API User checkbox on a user profile page. Check this box and save to enable API User status.

TrackVia Manage Users screen showing a user with API User status

The Manage Users screen showing an active API User account.

Step 2: Locate the API Key

The API Key is a unique identifier for your TrackVia account. It is used alongside the Auth Token to authenticate API requests.

How to Find Your API Key

In TrackVia, click your account name or avatar in the upper-right corner
Select My Account
Navigate to the API Access tab
Your API Key is displayed on this page — click the clipboard icon to copy it

TrackVia API Access tab showing the API Key with a clipboard copy icon

The API Access tab showing your account's API Key. Use the clipboard icon to copy it.

Important: The API Key is permanent — it cannot be changed or deleted. It is unique to your TrackVia account, not to an individual user.

How the API Key Is Used

Workato integrations: Enter the API Key in the Workato Connection form when setting up a TrackVia connection. See TrackVia Integrations: Auth Token Authentication for the full Workato connection setup steps.
Direct API calls: Pass the API Key as the user_key parameter in the header of every API request. Consult the TrackVia Developer Documentation for full API reference.

Step 3: Create an Auth Token

Auth Tokens are the primary credential used to authenticate integrations. Each token is associated with a specific API User and has its own expiration date. Super Admins can create up to 100 active Auth Tokens per account.

How to Create an Auth Token

Navigate to the API Access tab under My Account
Click Create Auth Token
In the dialog that opens, fill in the following fields:

Create Auth Token dialog showing Name of Token, Select User, and Expiration Date fields

The Create Auth Token dialog. All three fields must be set before saving — they cannot be changed after the token is created.

Name of Token: Choose a descriptive name that identifies the integration this token is for (e.g., "Salesforce Integration" or "Google Sheets Sync"). This makes it easy to identify and manage tokens later.
Select User: Choose the API User account to associate with this token. Only active users designated as API Users will appear in this list.
Expiration Date: Set any future date. The token will expire at midnight UTC on the selected date. Plan your rotation schedule before setting this date.

⚠ Important: Once an Auth Token is created, its name, associated user, and expiration date cannot be changed. If you make an error, you will need to deactivate the token and create a new one. Double-check all values before saving.

Click Create to generate the token
Copy the token value immediately using the clipboard icon — the full token value may not be displayed again after you navigate away

Auth Token list showing a newly created token with the clipboard copy icon

The Auth Tokens list after creation. Use the clipboard icon to copy the token value for use in your integration.

Managing Tokens

Auth Tokens can be viewed, copied, deactivated, and deleted from the API Access tab.

Auth Tokens list showing token name, user, and gear icon menu with Deactivate option

The Auth Tokens list showing the gear icon menu. Use this to deactivate or delete tokens.

Copying a token: Use the clipboard icon next to the token to copy it for use in an integration.
Deactivating a token: Click the gear icon next to the token and select Deactivate. Inactive tokens can be reactivated if needed.
Deleting a token: Inactive or expired tokens can be permanently deleted via the gear icon. This action cannot be undone.
Expired tokens: Tokens that have passed their expiration date cannot be reactivated or re-used — a new token must be created.

⚠ Impact of deactivating or expiring a token: Any active Workato Recipes or API integrations using a deactivated or expired token will immediately begin failing with a 401 Unauthorized error. Before deactivating a token, identify all integrations using it and update them with a replacement token to avoid an outage.

Token Expiry Notifications

Monitor your tokens' expiration dates proactively from the API Access tab. Tokens do not auto-renew — when a token expires, it stops working immediately at midnight UTC on the expiration date, and any integrations using it will fail. Plan a rotation schedule so replacements are created and deployed before existing tokens expire.

Auth Tokens list showing token name, associated user, and expiration date columns

Review the expiration dates of all active tokens regularly to plan ahead for rotation.

The 100-Token Limit

Each TrackVia account can have up to 100 Auth Tokens. To stay within this limit, periodically delete inactive and expired tokens that are no longer in use. If you approach the limit, contact TrackVia Support.

Security Best Practices

Do not share tokens — each integration should use its own dedicated token associated with its own dedicated API User account. Never share a token across multiple integrations or store it in plaintext in shared documents.
Use the principle of least privilege — assign each API User only the role permissions needed for that specific integration. Limiting access reduces the risk if credentials are ever compromised.
Rotate tokens on a schedule — set expiration dates deliberately and plan your rotation cycle. Create replacement tokens before existing ones expire, update your integrations, then deactivate the old tokens.
If a token is compromised — deactivate it immediately from the API Access tab, create a replacement, and update all affected integrations. Review Job History in Workato for any unauthorized activity during the exposure window.
Use dedicated API User accounts — do not use employee accounts for API integrations. Dedicated service accounts prevent disruption when employees leave and make credential management easier. See Workato: Best Practices for TrackVia Connections for full guidance.

TrackVia Integrations: Auth Token Authentication — Read this to set up a Workato Connection using your API Key and Auth Token after completing the steps in this article.
Workato: Best Practices for TrackVia Connections — Read this for guidance on creating dedicated API User accounts, configuring role permissions, and managing credentials over time.
Troubleshooting Common API Errors — Read this if your integration returns 401 Unauthorized or 403 Forbidden errors after setting up authentication.

For developer API reference documentation, visit the TrackVia Developer Documentation. For account-specific help, contact TrackVia Support.

Overview

Jump to Section