Zoomed Image
USA
800 691 9120
UK
01225 704844

API Tokens

xAssets Configuration Guide
REST API

API Tokens

This page describes scoped API tokens in xAssets. Scoped tokens provide limited, single-purpose access to specific operations without requiring the recipient to have a full xAssets user account or API key. They are designed for workflows where an external party needs to perform one action -- such as approving a purchase order or accepting delivery of an asset -- via a link in an email or notification.

Prerequisites

  • An xAssets instance with the REST API enabled
  • Administrator or Configuration access to set up token-generating workflows
  • A working SMTP configuration (tokens are typically delivered via email)

What Are Scoped API Tokens?

A scoped API token is a short-lived, single-use credential embedded in a URL. When a user clicks the link, xAssets authenticates them using the token and executes the associated operation -- no login screen, no password, no full session.

Key characteristics:

Property Description
Single-use Each token can only be used once. After use, it is invalidated.
Time-limited Tokens expire after a configurable period. Expired tokens return an error message.
Operation-scoped A token authorises exactly one operation (e.g., approve PO #1234). It cannot be used for any other purpose.
No session created Using a token does not create a full user session. The user cannot navigate the application.

Use Cases

Scoped tokens are particularly useful for:

  • Purchase order approval -- a manager receives an email with an "Approve" link. Clicking the link approves the PO without logging in.
  • Asset acceptance -- when an asset is delivered, the recipient clicks a link to confirm receipt.
  • Survey responses -- a user clicks a link to submit feedback or confirm information about an asset.
  • Incident acknowledgement -- a technician clicks a link to acknowledge an assigned incident.

How Tokens Work

The typical token flow is:

  1. A transformation or workflow generates a token for a specific operation and user.
  2. The token is embedded in a URL and sent to the recipient (usually by email).
  3. The recipient clicks the link.
  4. xAssets validates the token: checks it exists, has not been used, and has not expired.
  5. If valid, xAssets executes the associated operation and displays a confirmation page.
  6. The token is marked as used and cannot be reused.

Creating Tokens

Tokens are generated programmatically, typically from an AMSX transformation script. The process involves:

  1. Creating a token record with:
    • The target operation (API command and parameters)
    • The expiry period
    • An optional reference to the originating record (e.g., the PO or asset ID)
  2. Constructing a URL that includes the token
  3. Sending the URL to the recipient

Example: Purchase Order Approval Token

A typical PO approval workflow:

  1. A user submits a purchase order for approval.
  2. An AMSX transformation runs (triggered by the submission) and generates a scoped token.
  3. The transformation sends an email to the approver containing two links: one to approve, one to reject.
  4. The approver clicks "Approve" -- the token authenticates the action and updates the PO status.
  5. The submitter receives a notification that the PO was approved.

Security Considerations

Scoped tokens are designed to be secure, but administrators should be aware of the following:

Consideration Guidance
Token lifetime Set expiry periods as short as practical. A 72-hour window is typical for approval workflows.
Email security Tokens are only as secure as the email channel. For highly sensitive operations, consider requiring MFA in addition to the token.
Token reuse Tokens are single-use by design. Clicking the same link twice will show an error on the second attempt.
Audit trail All token-based operations are logged in the standard xAssets audit trail, showing the operation, timestamp, and token reference.
Forwarded emails If a recipient forwards the email, the token link will work for whoever clicks it first. Advise users not to forward approval emails.

Token Expiry

When a token expires without being used:

  • The link displays an expiry message to the user.
  • The associated operation is not executed.
  • The workflow may need to generate a new token if the action is still required.

Tip: Configure your approval workflows to send reminder emails before token expiry if the action has not been completed. This reduces the need for manual re-sending.

Differences from API Keys

Feature API Keys Scoped Tokens
Lifetime Permanent until revoked Time-limited (hours or days)
Reuse Unlimited requests Single use
Scope Full API access (limited by user group) One specific operation
Authentication Key + Secret pair Token in URL
Intended for System integrations End-user actions via email links