Looking for the previous version? View v2024.06 documentation →
API Tokens
Generate, manage, and revoke API tokens for external integrations with Data Trust.
Overview
The API Tokens section in System Preferences allows administrators to generate, manage, and revoke API tokens that external applications use to authenticate with the Data Trust REST API. Tokens can be scoped to specific business data views (BDVs), have their expiry date adjusted, be activated or deactivated independently, and have their full execution history reviewed. A migration utility is also provided to upgrade tokens from the older API format to the current one.
Prerequisites
- You are logged in to Data Trust with an Admin Pro-User role.
- Admin Console access has been granted by your system administrator.
Navigating to API Tokens
Path: Data Trust › Admin Console › System Preferences › API Tokens
Figure 1: System Preferences navigation option
Open Admin Console and click System Preferences to access all platform configuration tiles, including the API Tokens management section. Admin Console access is restricted to users with an Admin Pro-User role. The System Preferences landing page groups all platform-level settings in one place for easy navigation.
Figure 2: System Preferences options
The System Preferences page displays all available configuration tiles for the Data Trust instance. Locate the API Tokens tile to manage the tokens that external applications use to authenticate against the Data Trust REST API. If you have many tiles, scroll down or search for API Tokens to find it quickly.
Figure 3: API Tokens option tile
Click the API Tokens tile to open the token management page where all issued tokens are listed with their status, scope, and expiry information. From this page, you can create new tokens, adjust existing token settings, and revoke tokens that are no longer in use. Keeping the token list accurate and up to date is an important security practice for all Data Trust API integrations.
Figure 4: API Tokens action buttons
The API Tokens page lists all issued tokens with columns for token name, associated BDV scope, expiry date, and current status. Each row includes action buttons for activating, deactivating, regenerating, and viewing the history of that specific token. Review this list regularly to identify and revoke any tokens that are expired, unused, or belong to decommissioned integrations.
Scoping a Token to a Business Data View
- Select the token from the list and click the BDV selector.
Figure 5: Select BDV for token scoping
Scoping a token to a specific Business Data View (BDV) restricts the token's API access to only that BDV's resources, applying the principle of least privilege. Select the appropriate BDV from the dropdown to associate the token with that data domain. Tokens scoped to a BDV cannot access data or operations belonging to other BDVs, providing an important data isolation boundary for external integrations.
Figure 6: Copying the token text
Use the Copy button next to the token value to copy the full API token string to the clipboard for use in your API client configuration. The token string is shown only once after generation — if you navigate away without copying it, you will need to regenerate the token. Store the copied token securely in a secrets manager or vault and do not share it in plaintext via email or chat.
Changing Token Expiry Date
- Click the Change Expiry Date action on a token.
- Click Save to apply the new expiry date.
Figure 7: Change Expiry Date action
Each token row includes a Change Expiry Date action button that allows administrators to extend or shorten the token's validity window. Extending the expiry is useful for long-running integrations that do not support token rotation; shortening it can be used to enforce a tighter security policy. Clicking this action opens a date picker where you select the new expiry date and save the change.
Figure 8: Change Expiry pop-up
The Change Expiry pop-up displays the current expiry date and provides a date picker for selecting the new value. Choose a date that aligns with your organisation's token rotation policy — typically no more than 12 months in the future for production tokens. The new expiry will take effect immediately after saving; no restart or re-authentication is required.
Figure 9: Expiry Date selection pop-up
Use the calendar view in the date picker to select an appropriate future date for the token's expiry. Navigate through months using the arrow controls and click a specific day to set it as the new expiry date. Confirm the selected date is shown in the input field before clicking Save to apply the updated expiry.
Figure 10: Token saved successfully
A confirmation message indicates the token's expiry date has been updated and the new value is now active. The API Tokens list refreshes to show the updated expiry date next to the token entry. Inform the integration owner or development team of the new expiry date so they can update their calendar reminders for future renewal.
Activating and Deactivating Tokens
- To activate a token, click the Activate button on the token row.
- To deactivate a token without deleting it, click the Deactivate button.
Figure 11: Activate Token button
Clicking the Activate button on a deactivated token re-enables it for use in API calls. Only active tokens will be accepted by the Data Trust API; requests using a deactivated token will receive an authentication error. Activating a previously deactivated token does not change its existing BDV scope or expiry date.
Figure 12: Token activated successfully
A success message confirms the token is now active and will authenticate API requests immediately. Verify the token status in the API Tokens list to confirm it shows an Active state. Test the integration that uses this token to confirm it can once again make successful API calls to Data Trust.
Figure 13: Deactivate Token button
Clicking the Deactivate button on an active token suspends it without permanently deleting it, making it easy to re-enable if needed. This is useful for temporarily blocking an integration during a security review, a system migration, or a maintenance window. All integrations using this token will start receiving authentication errors immediately after deactivation.
Figure 14: Token deactivated successfully
A confirmation message indicates the token has been deactivated and all API requests using this token will now be rejected. The token remains visible in the API Tokens list with a Deactivated status so it can be reactivated later if required. Document the reason for deactivation in your change management system to maintain an audit trail.
Viewing API Execution History
- Click the History button on a token to view its usage log.
Figure 15: History button on token row
The History button on each token row opens a detailed log of all API calls made using that specific token, including timestamps, endpoints, and HTTP response codes. Use this history to audit token usage patterns or to investigate unexpected API behaviour reported by integration owners. The history view is read-only and cannot be cleared by administrators, ensuring a tamper-evident audit trail.
Figure 16: API Execution History log
The API Execution History log displays each call's date, time, caller IP, endpoint path, and HTTP response status code in a sortable grid. Filter by date range or status code to quickly identify failed requests that may indicate integration issues or unauthorised access attempts. Export the history log if you need to share it with your security team for a formal audit or incident response review.
Regenerating an API Token
- Click Regenerate API Token on the desired token.
Figure 17: Regenerate API Token action
The Regenerate API Token action replaces the existing token string with a new cryptographically generated value while preserving all other token settings such as BDV scope and expiry date. Use this action as part of your regular token rotation policy or in response to a suspected token compromise. Coordinate with all teams whose integrations use this token before regenerating, as the old token will be immediately invalidated.
Figure 18: Regenerate Token confirmation pop-up
The Regenerate Token confirmation pop-up asks you to confirm the action before proceeding, because the old token string is immediately and permanently invalidated upon confirmation. Any API clients still using the old token string will begin receiving authentication errors the moment you confirm. Click Confirm only after all stakeholders have been notified and are ready to update their integration configurations with the new token value.
Figure 19: Token regenerated and saved successfully
A success message confirms the new token string has been generated and saved; the new value is displayed on screen immediately after confirmation. Copy the new token value before navigating away — it will not be shown again after you leave this page. Distribute the new token securely to all teams whose integrations rely on it so they can update their configuration without delay.
Migrating Old API Tokens to the New Format
- Click Migrate Old API to New to upgrade legacy tokens.
Figure 20: Migrate Old API to New action
The Migrate Old API to New action converts tokens created under the previous Data Trust API version to the current format without disrupting existing integrations. Performing this migration is recommended after a platform upgrade to ensure all tokens comply with the latest security standards and API capabilities. The migration preserves the token string value, BDV scope, and expiry date, so integrations continue working without requiring any changes on the client side.
Figure 21: Migrate Old API to New API pop-up
The migration pop-up lists the legacy tokens identified for upgrade and provides a summary of the changes that will be applied during the migration. Review the listed tokens carefully to confirm all selected tokens are safe to migrate before clicking Confirm. After confirming, Data Trust converts the selected tokens and updates their status in the API Tokens list to reflect the new format.
Refreshing the Token List
Figure 22: Refresh button
Click the Refresh button to reload the API Tokens list and display any recent changes made by other administrators or automated processes. This is useful in environments where multiple administrators may be managing tokens concurrently, ensuring your view is up to date before making changes. Refreshing does not affect the state of any token — it simply updates the display to reflect the latest data from the server.
Figure 23: Menu button for additional token actions
The menu button on the API Tokens page provides access to additional bulk management options, such as exporting the token list or performing bulk status changes. Use the bulk options when managing a large number of tokens, for example during a scheduled security review that requires deactivating multiple tokens simultaneously. Exercise caution with bulk operations as they affect all selected tokens at once and some actions cannot be undone.