Claiming a device

Claiming is the interactive way to take ownership of a device. A device flashed without an auto-join token still registers itself with Pantahub on first boot — but as an unclaimed device that belongs to nobody. Alongside its new device ID it receives a one-time challenge secret, which the device exposes to whoever is physically holding it. Enter that ID and challenge in the Hub while logged in, and the device becomes yours.

The challenge is the proof of ownership: only someone with access to the device (its console, its screen, or its local network) can read it, so only that person can claim the device.

The flow

1. The device registers unclaimed

On first boot, Pantavisor registers the device with Pantahub. Without an auto-join token there is no owner to assign, so the device record is created unclaimed: it exists in the registry but belongs to no account. The response gives the device its identity (device-id), its permanent credentials (creds.secret), and the one-time challenge.

2. The device exposes its ID and challenge

Pantavisor stores the ID and challenge locally (visible on the device's console/logs, and to containers under /pantavisor/). Depending on the device and how you provision it, you get them as:

• Console output — boot logs print the device ID and challenge.
• A QR code / link — images from the Hub's Start a new device flow can present a link to the claim page with both values prefilled.
• Wi-Fi provisioning — when you hand the device your network credentials with Provision Wi-Fi (/provision-wifi), the Hub stays connected to the device over Bluetooth until it reaches the internet and obtains its challenge, then sends you straight to the claim form, prefilled.

3. You claim it in the Hub

Open Claim Device (/claim) while logged in and enter the device ID and challenge — or follow a prefilled link (/claim?id=…&challenge=…). On mobile you can scan the device's QR code instead of typing. Under the hood this is a single API call:

PUT /devices/{device-id}?challenge=<challenge>

authenticated with your user token. Pantahub verifies the challenge, assigns the device to your account, and invalidates the challenge — it is one-time, so a claimed device cannot be claimed away from you.

The same claim can be done from the command line with the pvr CLI:

pvr claim -c <challenge> https://api.pantahub.com/devices/<device-id>

4. The device is yours

The device now appears in your Devices list and behaves exactly like one onboarded any other way: it authenticates with its own creds.secret, posts its factory state as revision 0, and you manage it through its trail (see Deploying updates). Nothing changes on the device — it doesn't even need to be online at the moment you claim it.

Notes

• A claim needs physical or local access. Anyone who can read the challenge (console, QR, local network) before you do can claim the device. Claim devices promptly once they boot in an environment you don't fully control.
• Unclaimed is a limbo state. An unclaimed device can talk to the API only enough to keep its registration alive; it can't be managed by anyone until claimed, and stale unclaimed registrations are eventually garbage collected. Re-registering (or re-flashing) produces a fresh ID and challenge.
• Claiming doesn't scale to fleets. It is deliberately one-device, one-human. For batches, bake an auto-join token into the image instead — and see How onboarding works for choosing between the routes.