Onboard a Device¶

What this is: giving a non-human thing — a drone, a sensor, a data feed, an API — its own identity so it can join the system. When you'd do it: a new piece of kit or automated feed needs to participate, and it doesn't have a login yet. How long it takes: about two minutes to create the profile and generate the token; handing it off to whoever is setting up the device may take a little longer.

Who can do this: an Admin. These screens only show up if your own login has the Admin role. A normal Operator login won't see them — if the menu below isn't there, ask an admin to do this or to upgrade your access.

Some things that aren't people still need to join — a drone, a sensor, a feed. This gives them their own identity. You'll do everything on the Directory website. No command line, no technical steps.

The shape of it¶

flowchart LR
    A["You create the<br/>device profile"] --> B["Site gives you<br/>an enrollment token"]
    B --> C["You hand the token<br/>to the device team"]
    C --> D["Device uses it<br/>to join — done"]

You make the profile, the site hands you a one-time code, you pass that code to whoever is setting up the device, and the device uses it to join. That's it.

Before you start¶

You're signed in to the Directory site as an admin.
You know what the device is called — you'll need a Callsign (e.g. WASP-01).
You know its Platform Type (drone, sensor, feed, etc.) — you'll pick from a list.
You have a way to securely hand the enrollment token to whoever is configuring the device (a secure message, a shared channel, or doing it side by side).

Steps¶

Open the devices list. In the top menu, click Devices — it's its own top-level item (alongside Principals), not a section inside Principals.
Start a new one. Click the button to create a new device. A form opens with the title Create Device.
Fill in the form:
Callsign — the device's identifier, e.g. WASP-01. This is how it appears everywhere in the system.
Unit — the team or unit it belongs to, e.g. 1 Platoon, A Coy. Optional — skip it if you're not sure.
Server Address — leave blank unless this is a server or gateway device. Only needed for machines that hold a Directory-signed identity directly.
Platform Type — pick the type that matches the device from the dropdown.
Role — leave it on Machine for a normal device (drone, sensor, feed). Only pick Server or Gateway if this device routes traffic for others.
Coverage Area — click cells on the map to mark where this device operates. At least one cell is required.
Save it. Click Create Device. You'll land on the new device's page.
Generate an enrollment token. Scroll down to the Pending Registration Tokens panel. Click Generate Registration Token. A token appears on screen under the heading One-time registration token (copy now — will not be shown again).

Copy it now. The page shows the token once only — if you navigate away without copying it, you'll need to revoke it and generate a fresh one. Treat it like a temporary password: one use, and it expires.

Hand off the token. Pass it securely to whoever is configuring the device — over a secure message channel, or by reading it out in person. They enter or paste it into the device's setup process. The device uses it to check in and receives a full identity in return.

How to know it worked¶

The device's page shows a green active badge next to its callsign.
The Pending Registration Tokens panel shows No pending tokens — the token was consumed by the device.
The Device Credentials panel shows a Last issued date and a partial public key.

If something goes wrong¶

You navigated away before copying the token. The token value is gone — it was shown once only. Go back to the device's page, find the token in the Pending Registration Tokens table, and click Revoke next to it. Then click Generate Registration Token again to get a fresh one.
The device setup failed — the token was never used. Same recovery: click Revoke on the unused token, generate a new one, and try again.
The device enrolled but something needs fixing (wrong callsign, wrong unit). Click Edit on the device's page and update the fields.
The device's credentials need replacing — key was lost or setup needs a fresh start. On the device's page, scroll to the Device Credentials panel and click Reissue Credentials. This generates a new keypair. The team managing the device will need to deploy the new credentials.
You picked the wrong role. Click Edit on the device's page and change it.