Asset Identifiers

Every asset has a unique identifier, and there are three identifier types worth telling apart. You will meet all three the first time you script against the API or update a forwarder by hand.

Identifier	What it is
Asset ID	The unique ID of one asset. This is what an API call or a UI reference means by "the asset"
Default Asset ID	A built-in asset in every environment, named `__DefaultAsset__`, for uploads that do not belong to any particular machine
Maintenance token	A short-lived, environment-scoped token that authorizes forwarder maintenance such as an uninstall or an update. Valid for 14 days
Registration key	What decides whether a registering forwarder joins an existing asset or creates a new one. Derived automatically, and overridable

How do I find an asset's ID?

Three routes, depending on where you are standing.

From the Assets list. Go to app.stairwell.com/assets, find the asset, and read the Identifier column.

From the asset panel. Select the asset and read the value next to ID.

From a Windows machine itself, when you have the host but not the console. Open regedit and read HKLM\Software\Stairwell\Inception\AssetId.

That last one is the useful one during an incident, because it works from the machine you are already logged into.

What is the Default Asset ID for?

Uploads that are not about a particular machine.

The file intake API requires a valid Asset ID on every upload. Uploading through the UI picks the default asset for you, which is why the requirement is invisible until you script it. Through the API you have to supply one, and if the file did not come from a specific endpoint, the default asset is the correct answer rather than a workaround.

To find it: open app.stairwell.com/assets, select the Assets tab, find the asset named __DefaultAsset__, select the row, and read the value next to ID.

This is the single most common reason a first API upload fails. See REST APIs and swell, which reads a configured asset ID so you are not passing one on every command.

What is the registration key?

When a forwarder registers, it sends a registration key -- an idempotency key -- alongside the request. Stairwell looks for an asset in that environment already carrying the same key. If it finds one, the forwarder adopts that existing asset and its whole history. If it does not, a new asset is created.

That single lookup is what keeps a forwarder restart, a reinstall, or an upgrade from filling your fleet with duplicates. It is also what keeps two machines that happen to share a hostname apart, because the key includes more than the name.

Each platform derives one for you:

Platform	Default key	How to set it explicitly
Windows	`<hostname>@<MAC>` of the primary adapter	`STAIRWELL_REGISTRATION_KEY` machine environment variable
macOS	Computer name plus the primary MAC	`STAIRWELL_REGISTRATION_KEY` in the Stairwell preferences payload your MDM delivers
Linux	Hostname plus the primary MAC	`asset.idempotencyKey` in `/etc/stairwell/config.json`

Keys are compared case-insensitively, and they are scoped to an environment: the same key in two environments is two assets, correctly.

When the default is not good enough

The default is hostname plus MAC, so it breaks in exactly the situations where those two are not stable and unique.

The MAC changes and the hostname does not. Replacing a NIC, re-imaging, or a VDI pool that regenerates addresses all produce a new key, so the machine arrives as a second asset. Its history splits in two and neither half tells you that.
A clone keeps both. A VM template captured after the forwarder was installed hands the same hostname and MAC to every machine built from it. They collide into one asset, and a fleet of them reports as a single machine.
On Windows, the MAC may be missing. If the primary adapter cannot be read, the forwarder falls back to the hostname alone. Two machines that share a name then share an asset.

The fix in all three cases is the same: set the key yourself, to something that identifies the physical or virtual machine and does not move. A hardware serial number or a cloud instance ID is the usual choice.

🚧
Set it before the first registration, not after
The key is read at registration. Changing it on a machine that has already registered does not rename or merge anything -- it makes that machine register again, as a new asset, leaving the old one behind to age out. Decide the scheme before a rollout rather than during one.

If you already have duplicates or collisions, contact support rather than trying to unpick it from the endpoint. See Who to Contact for Support.

How do I get a maintenance token?

Go to app.stairwell.com/assets.
If you manage several environments, select the right one first. The token is scoped to it.
Select Forwarder Maintenance Token, then Generate.
Copy it somewhere safe.

Two properties to plan around. Tokens expire after 14 days, so one generated for a rollout that slips will need regenerating. And a token is tied to one environment, so a token that works on one fleet fails on another with an error that reads like a bad token rather than the wrong one.

What should I read next?

Assets, for what an asset is and why its record outlives the machine.
Environments, since two of the three identifiers here are environment-scoped.
REST APIs, which is where the Asset ID requirement shows up first.
Asset Registration Rules, for what happens to an asset once it has registered.