Integrations - API Keys, Webhooks, and Microsoft Entra ID

Overview

The Integrations section lets you connect UniAsset to external systems — IoT platforms, ERP systems, automation tools, and your Microsoft directory. It is split into five areas accessible from the sub-navigation:

Who Can Access This

Admins and Members are redirected away from the API Keys, Webhooks, and Developer Guide pages.

Security note: API keys grant write access to your UniAsset data. Store them in secret managers, never in source code or client-side environments.

How to Access

1. Log in to your UniAsset account
2. Click Settings in the left sidebar
3. Select Integrations

Plan Requirements

The integration API middleware enforces the Enterprise plan at the authentication layer — requests using an API key on any lower plan receive a 403 ENTERPRISE_REQUIRED error even if the key was created.

---

API Keys

What API keys are for

API keys allow external systems to authenticate with the UniAsset integration API and perform write operations on your data — such as creating assets, logging maintenance, updating assignments, and reporting GPS positions.

Key format

All keys are prefixed ua_live_ followed by 64 random hex characters, for example:

ua_live_a1b2c3d4e5f6...

Keys are never stored in plain text. UniAsset stores only a bcrypt hash and a short lookup prefix (the first 12 characters). The full key is shown only once — at the moment of creation.

API key permissions

When creating a key, you select one or more permissions that scope what the key can do:

A key with no permissions assigned cannot perform any write operations.

How to create an API key

1. Navigate to Settings > Integrations > API Keys
2. Click Create API Key
3. Enter a descriptive name (e.g. "ERP Connector – Production")
4. Select the permissions this key needs
5. Click Create
6. Copy the full key immediately — it will not be shown again

API key registry

The API Keys page lists all keys for your organization with:

• Name — the label you gave the key
• Key prefix — the first 12 characters (e.g. ua_live_a1b2…) used to identify the key without exposing it
• Permissions — the scopes assigned
• Last used — timestamp of the most recent authenticated request, or "Never"
• Created — date and the user who created the key

Revoking an API key

To revoke a key, open its actions menu and select Revoke. Revoked keys are immediately rejected by the API — any system using that key must be updated with a new one. Revoked keys remain visible in the registry for audit purposes.

Using an API key

Pass the key as a Bearer token in the Authorization header of every request:

Authorization: Bearer ua_live_xxxxx...

The server derives your tenant identity from the key — never from a request body field.

---

Webhooks

What webhooks are for

Webhooks let UniAsset push real-time notifications to your own systems when events occur. Instead of your system polling for changes, UniAsset sends a signed HTTP POST to your endpoint the moment an event fires.

How webhook delivery works

1. An event occurs in UniAsset (e.g. an asset is created)
2. A delivery job is written to the queue for every active webhook that subscribes to that event
3. A background processor sends a signed HTTP POST to each endpoint
4. The delivery result (success or failure) is recorded in the Activity Log

Delivery is asynchronous — the original action completes immediately regardless of webhook delivery status.

Webhook payload format

Every delivery is a JSON POST with the following structure:

{
  "event": "asset.created",
  "timestamp": "2026-03-08T09:15:00.000Z",
  "data": {
    "assetId": "asset_123",
    "assetName": "Forklift A-17",
    "categoryName": "Vehicles",
    "statusName": "ACTIVE"
  }
}

Webhook request headers

Each POST includes these headers for verification:

Verifying webhook signatures

Compute HMAC-SHA256 over the raw request body using your webhook's secret as the key, and compare it to the X-UniAsset-Signature header. Reject requests where the signatures do not match.

UniAsset has a 10-second timeout per delivery attempt. Endpoints that do not respond within 10 seconds are treated as failed.

Available webhook events

How to create a webhook

1. Navigate to Settings > Integrations > Webhooks
2. Click Create Webhook
3. Enter a name (e.g. "ERP Event Sink")
4. Enter the endpoint URL (must be HTTPS and publicly reachable)
5. Select the events you want to subscribe to (one or more)
6. Click Create — a signing secret is generated automatically

Webhook status indicators

Each webhook row shows a health badge:

Managing webhooks

Each webhook has an actions menu with the following options:

• Send Test Event — immediately queues a asset.created test delivery to verify your endpoint is reachable
• Edit — update the name, URL, or event subscriptions
• View Logs — opens the Activity Log filtered to this webhook
• Pause / Resume — temporarily suspend or re-enable deliveries without deleting the webhook
• Delete — permanently removes the webhook and all queued deliveries for it

---

Activity Log

The Activity Log shows the last 100 API requests and the last 100 webhook delivery attempts, merged and sorted by most recent first.

Access: Owner, Admin, and Manager roles.

Log columns

Clicking any row expands the full payload and headers for debugging.

API log status categories

• 2xx — success
• 4xx / 5xx — failed

Webhook delivery statuses

Sensitive fields in logged request bodies (passwords, tokens, secrets, credit card data) are automatically redacted to [REDACTED] before storage.

---

Microsoft Entra ID Directory Sync

Microsoft Entra ID integration (formerly Azure AD) allows you to automatically provision and deprovision UniAsset users from your Microsoft directory. This is an Enterprise-only feature.

What it does

• Syncs users and security groups from your Microsoft tenant into UniAsset
• Automatically provisions new users when they are added to mapped groups
• Can deprovision users when they are removed from the directory (configurable)
• Maps Entra groups to UniAsset roles

Plan requirement

The Entra ID page is accessible to all authenticated users but shows a plan-gate overlay on all plans below Enterprise. The entraDirectorySync limit flag is only true on the Enterprise plan.

Setup overview

1. Navigate to Settings > Integrations > Microsoft Entra ID
2. Connect your Microsoft tenant using the OAuth flow (requires a Microsoft admin account with directory read permissions)
3. Once connected, the page shows your verified domain and last sync timestamp
4. Use the Group Mapper section to map your Entra security groups to UniAsset roles (Owner, Admin, Member, Viewer)
5. Configure Auto Provision and Deprovision Sync options:
   • Auto Provision — automatically creates UniAsset accounts for synced group members
   • Deprovision Sync — removes UniAsset access when a user is removed from the group in Entra

Group mapping

Once connected, your Microsoft security groups are listed. Assign each group a UniAsset role. Users in that group who are provisioned will receive the mapped role.

Connection health

If the Microsoft Graph token becomes stale, the group list on the page will be empty rather than returning an error — the connection status is shown at the top of the page. Re-authenticate to refresh the token.

---

Developer Guide

The Developer Guide page (Owner only) provides copyable example requests for all integration API endpoints:

All requests use Authorization: Bearer ua_live_... and return JSON.

---

Important Notes & Limitations

API keys are shown only once

• Copy and store the full key immediately after creation. There is no way to retrieve it afterwards — revoke and create a new key if it is lost.

Enterprise plan is required to use API keys

• The API key management UI is accessible to Owners on any plan, but the integration API itself rejects requests from tenants on plans below Enterprise with a 403 ENTERPRISE_REQUIRED error.

Webhook delivery is asynchronous

• Events are queued and sent by a background processor. Your endpoint will receive the POST within seconds of the event, but not synchronously within the same request cycle.

Webhook endpoints must return 2xx within 10 seconds

• Endpoints that time out or return non-2xx responses are recorded as failed deliveries. Check the Activity Log for error details.

Deleting a webhook also deletes all queued deliveries

• Pending deliveries for a deleted webhook are discarded. Pause instead of deleting if you need to temporarily stop deliveries.

Activity Log retains the last 100 entries per type

• The page shows the 100 most recent API calls and 100 most recent webhook deliveries. Older records are not shown in the UI (though they remain in the database).

Microsoft Entra ID requires an Enterprise plan

• Upgrading from Enterprise is not self-serve. Contact sales via Settings > Billing & Plans.

---

Frequently Asked Questions

I created an API key but my requests are getting 403 ENTERPRISE_REQUIRED — why?

The integration API requires an Enterprise plan regardless of which plan tier shows apiAccess: true in the feature list. API key creation is available on Growth and above, but actual API authentication enforces Enterprise. Contact sales to upgrade.

Can I have multiple API keys?

Yes. You can create as many keys as needed — for example, one per external system or environment. Each key has its own permission scope and can be revoked independently.

How do I rotate an API key?

Create a new key with the same permissions, update your external system to use the new key, then revoke the old key. There is no in-place rotation.

Can I subscribe a webhook to all events at once?

No. You must select events individually when creating or editing a webhook. Subscribe only to the events your endpoint needs to minimize unnecessary traffic.

My webhook shows "Failing" — what should I check?

Go to Activity Log and filter by the webhook. Check the status and error details column for the failed deliveries. Common causes are: endpoint unreachable, TLS certificate errors, response timeout (>10 seconds), or the endpoint returning a non-2xx status.

Can I test my webhook without waiting for a real event?

Yes. Click Send Test Event in the webhook's action menu. This queues an asset.created test delivery immediately, regardless of whether any assets have been created.

Who can see the Activity Log?

Owners, Admins, and Managers. Members and Viewers cannot access it.

Is Microsoft Entra ID the same as Azure Active Directory?

Yes — Microsoft renamed Azure AD to Microsoft Entra ID. The integration connects to the Microsoft Graph API and works with both the legacy Azure AD and the rebranded Entra ID.