Zoomed Image
USA
800 691 9120
UK
01225 704844

API Getting Started

xAssets Configuration Guide
REST API

API Getting Started

This page walks you through creating an API key, authenticating, and making your first API call. By the end, you will have a working pattern for querying and saving data through the xAssets REST API.

Prerequisites

  • An xAssets instance accessible from your development machine
  • Administrator access to xAssets (to create API keys)
  • A tool for making HTTP requests (e.g., Postman, curl, or a programming language with HTTP support)

Step 1: Create an API Key

API keys control who can access the API and what data they can see. Each key is associated with a user group that determines its permissions.

  1. Navigate to Admin > Settings
  2. Open the API Keys section
  3. Click New to create a new API key
  4. Enter a description for the key (e.g., "Integration with HR System")
  5. Set the User Group to control what data this key can access. The key inherits the same data visibility as users in that group.
  6. Save the record -- the system generates a Key and Secret
  7. Copy both values immediately -- the Secret is only shown once

Warning: Treat the API Secret like a password. Do not store it in source code, share it in emails, or expose it in client-side applications. Use environment variables or a secrets manager.

Step 2: Authenticate

Send a POST request to obtain a bearer token:

POST https://your-server/a.aspx
Content-Type: application/x-www-form-urlencoded

apikey=YOUR_API_KEY&apisecret=YOUR_API_SECRET&command=logon

The response includes a bearer token in the Authorization field. Store this token for use in subsequent requests.

Tip: If you receive an "Invalid API Key" error, verify that you are using the correct Key (not the Secret) in the apikey field, and that the API key has not been disabled.

Step 3: Query Data

Use the bearer token to retrieve data. This example retrieves the XML data for a single asset:

POST https://your-server/a.aspx
Authorization: Bearer YOUR_TOKEN
Content-Type: application/x-www-form-urlencoded

command=commandprocessor&commandname=AssetXML&id=1001

This returns the full XML representation of the asset with ID 1001, including all fields, specification data, and related records.

Step 4: Save Changes

After modifying the XML, save it back to xAssets:

POST https://your-server/a.aspx
Authorization: Bearer YOUR_TOKEN
Content-Type: application/x-www-form-urlencoded

command=save&savexml=YOUR_MODIFIED_XML

The response confirms the save was successful or returns an error message if validation failed.

JSON Output

By default, API responses return XML. To receive JSON output, add &json=true to your request:

command=commandprocessor&commandname=RunQuery&queryname=All Assets&json=true

JSON responses use a standard structure:

{
  "columns": ["AssetID", "AssetDesc", "CategoryID"],
  "rows": [
    {"AssetID": 1001, "AssetDesc": "Dell Latitude 5520", "CategoryID": 1}
  ],
  "rowCount": 1
}

Testing with Postman

xAssets provides a Postman collection for testing API calls. To use it:

  1. Import the collection into Postman (contact xAssets support for the collection file)
  2. Create a Postman environment with variables for your server URL, API key, and API secret
  3. Run the "Logon" request first to obtain a bearer token
  4. Use the token in subsequent requests

Postman is the recommended tool for exploring and testing the API before writing production code.

Error Handling

API errors return an HTTP 200 status with an error message in the response body. Always check the response for error indicators before processing results.

Common errors and their solutions:

Error Cause Solution
Invalid API Key The API key or secret is incorrect Verify the key and secret values. Ensure the key has not been disabled.
Session Expired The bearer token has timed out Call the logon endpoint again to obtain a new token
Insufficient Permissions The API key's user group lacks access to the requested data or operation Change the user group assigned to the API key, or grant the required permissions to the group
Invalid XML The save XML is malformed or contains invalid field values Validate the XML structure and check field names against the data model

Tip: During development, start with a broad-permission user group to avoid permission errors while testing, then restrict to minimum-necessary permissions before going to production.

Next Steps

Once you can authenticate and make basic requests: