Zoomed Image
USA
800 691 9120
UK
01225 704844

API Key Management

xAssets Configuration Guide
REST API

API Key Management

This page describes how to create, manage, rotate, and revoke API keys in xAssets. API keys are long-lived credentials used by external systems to authenticate with the xAssets REST API. Each key is associated with a user group that determines its data access permissions.

Prerequisites

  • Administrator access to xAssets
  • At least one user group configured to assign to API keys
  • An understanding of the REST API Overview and how API authentication works

Accessing the API Key Management Screen

Navigate to Admin > Settings and open the API Keys section. This screen lists all API keys in the system, showing their description, associated user group, creation date, and status.

Creating a New API Key

  1. From the API Keys list, click New.
  2. Enter a Description that identifies the purpose of this key (e.g., "HR System Integration", "Azure AD Sync", "Monitoring Dashboard").
  3. Select a User Group. The API key inherits the same permissions as users in this group -- table access, record filters, and menu permissions all apply.
  4. Save the record.
  5. The system generates a Key and Secret pair.
  6. Copy both values immediately. The Secret is displayed only once at creation time. If you lose the Secret, you must generate a new key.

Warning: Treat API Secrets with the same care as passwords. Store them in a secrets manager or environment variables -- never in source code, configuration files checked into version control, or shared documents.

Choosing the Right User Group

The user group assigned to an API key controls what the key can access:

Scenario Recommended Group
Full administrative integration A dedicated API Admin group with broad permissions
Read-only reporting A group with read permissions only
Department-specific integration A group with record filters limiting data to one department or company
Single-purpose automation A group with minimal permissions -- only the tables and operations the integration requires

Tip: Create dedicated user groups for API keys rather than reusing groups shared with interactive users. This makes it easy to audit and restrict API access independently of user access.

Viewing Existing Keys

The API Keys list shows:

Column Description
Description The human-readable name for the key
User Group The user group controlling this key's permissions
Key The API Key value (always visible)
Secret Shown as masked after creation -- cannot be retrieved
Status Active or Disabled
Created When the key was created

Click any row to edit the key's description, user group, or status.

Revoking an API Key

To immediately prevent an API key from being used:

  1. Open the key's record from the API Keys list.
  2. Set the status to Disabled.
  3. Save the record.

Disabled keys cannot authenticate. Any system using the disabled key will receive an "Invalid API Key" error on its next request.

Important: Disabling a key takes effect immediately. Ensure the consuming system has been updated with a replacement key before disabling the old one, or be prepared for the integration to stop working.

To permanently remove a key, delete the record. Deleted keys cannot be recovered.

Rotating API Keys

Key rotation is the practice of periodically replacing API keys to limit the impact of a compromised credential. To rotate a key:

  1. Create a new API key with the same user group and description (append a version or date for clarity, e.g., "HR Integration - March 2026").
  2. Update the consuming system to use the new Key and Secret.
  3. Verify the integration works with the new key.
  4. Disable the old key.
  5. After a monitoring period, delete the old key.

Tip: Schedule key rotations quarterly or semi-annually. Add a reminder to your calendar or batch job schedule. Frequent rotation limits the window of exposure if a key is compromised.

Security Best Practices

Practice Why
One key per integration If one system is compromised, you can revoke its key without affecting others.
Minimum permissions Assign the narrowest user group that satisfies the integration's requirements.
Regular rotation Replace keys periodically even if no compromise is suspected.
Monitor usage Review User Logon History to identify unused or suspicious API key activity.
Separate environments Use different keys for development, staging, and production. Never share keys across environments.
Secret storage Use environment variables or a secrets manager. Never hard-code secrets.

Troubleshooting

Problem Cause Solution
"Invalid API Key" error Key is disabled, deleted, or the Secret is incorrect Verify the Key and Secret. Check if the key has been disabled.
"Insufficient Permissions" error The key's user group lacks access to the requested operation Edit the key's user group or assign a group with broader permissions.
Integration stopped working unexpectedly Key was rotated or disabled by another administrator Check the API Keys list for recently modified keys.
Cannot retrieve the Secret Secrets are only shown at creation time Create a new key and update the consuming system.