Devices service

/devices is the device registry: every Pantavisor device is a record here, with an owner, a secret, metadata, and optionally a public flag. Concepts: Devices; UI workflows: Devices guide and the onboarding guides.

Register a device

As a logged-in user (the device is immediately yours):

curl -s -X POST https://api.pantahub.com/devices/ \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"secret":"yourdevicesecret"}'

Or unauthenticated, the way a stock image does on first boot — the device registers unclaimed and receives a one-time challenge:

curl -s -X POST https://api.pantahub.com/devices/ \
  -H 'Content-Type: application/json' -d '{"secret":"mysec1"}'

The response has a challenge but an empty owner. An authenticated user claims it by resolving the challenge:

curl -s -X PUT \
  "https://api.pantahub.com/devices/<device-id>?challenge=<challenge>" \
  -H "Authorization: Bearer $TOKEN"

The challenge is cleared and the owner set — this is exactly the flow behind Claiming a device.

Device tokens (auto-assign)

The built-in factory story: create a token, bake it into images, and every device registering with it is assigned to you automatically — see Auto-join tokens for the full picture.

# create a token; optionally attach default user-meta for joining devices
curl -s -X POST https://api.pantahub.com/devices/tokens \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"default-user-meta":{"batch":"2026-q3"}}'

The token value in the response is one-time visible. Devices pass it at registration in the Pantahub-Devices-Auto-Token-V1 header:

curl -s -X POST https://api.pantahub.com/devices/ \
  -H 'Pantahub-Devices-Auto-Token-V1: <token>'

GET /devices/tokens lists your tokens; DELETE /devices/tokens/<id> disables one (already-joined devices keep working — they authenticate with their own secret).

Everyday operations

# list your devices
curl -s https://api.pantahub.com/devices/ -H "Authorization: Bearer $TOKEN"

# look one up by id, PRN or nick
curl -s https://api.pantahub.com/devices/<id-or-nick> \
  -H "Authorization: Bearer $TOKEN"

# rename (409 Conflict if the nick is taken)
curl -s -X PATCH https://api.pantahub.com/devices/<id> \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"nick":"mynewnick"}'

# rotate the device secret
curl -s -X PUT https://api.pantahub.com/devices/<id> \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"secret":"mynewsecret"}'

Metadata: user-meta and device-meta

Each device carries two key/value maps with opposite writers:

• user-meta — written by the owner, read by the device. Labels, configuration you push down.
• device-meta — written by the device (logged in as itself), read by the owner. Hardware info, network state, anything the device reports.

# as the owner
curl -s -X PUT https://api.pantahub.com/devices/<id>/user-meta \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"location":"lab-3","role":"gateway"}'

# as the device (DTOKEN from a device login — see the auth service)
curl -s -X PUT https://api.pantahub.com/devices/<id>/device-meta \
  -H "Authorization: Bearer $DTOKEN" -H 'Content-Type: application/json' \
  -d '{"fw-variant":"imx8-dev"}'

Public devices

A device can be shared read-only with the world via the public flag — PUT /devices/<id>/public sets it, DELETE on the same path clears it. Anyone can then list a user's public devices:

curl -s "https://api.pantahub.com/devices/?owner-nick=<nick>"

(owner=<prn> works too.)

Endpoint reference

Try any of these live in the API Reference:

Endpoint	Reference
POST /devices	Register device
PUT /devices/{id}	Claim / update
GET /devices	List devices
GET /devices/{id}	Get device
PATCH /devices/{id}	Patch (nick, …)
DELETE /devices/{id}	Delete device
PUT /devices/{id}/user-meta	Set user-meta
PATCH /devices/{id}/user-meta	Patch user-meta
PUT /devices/{id}/device-meta	Set device-meta
PUT /devices/{id}/public	Mark public
DELETE /devices/{id}/public	Unmark public
POST /devices/tokens	Create device token
GET /devices/tokens	List device tokens
DELETE /devices/tokens/{id}	Disable device token
GET /devices/{id}/ownership/validate	TLS ownership validate