Auto-join tokens

An auto-join token (device token) is Pantahub's built-in factory story: a secret you bake into device images so that every device flashed with it registers itself into your account on first boot — no interactive login, no per-device configuration. (For how this compares to the other onboarding routes, see How onboarding works.)

How it works

1. Create the token

Under Device tokens (/devices/tokens/new), give the token a nick and create it. The secret is one-time visible: it is shown only in the creation response, never again. If you lose it, create a new token — the old one can stay active as long as you don't believe it has been compromised.

Optionally attach default user-meta: a set of key/value pairs that will be placed on every device joining through this token. Use it to label a batch by factory, hardware revision, customer, and so on.

2. Bake it into the image

Configure the device at the factory to use the token as its Pantahub registration credential. Images downloaded from the Hub's Start a new device flow come preconfigured this way.

3. Device joins on first boot

When Pantavisor registers the device for the first time, it passes the token in the Pantahub-Devices-Auto-Token-V1 header. Pantahub then:

• creates the device record and assigns it to the token's owner — you,
• applies the token's default user-meta to the device,
• issues the device its own credentials (creds.secret) for all later authentication.

The token is only involved in this first registration. From then on the device authenticates with its own per-device credentials, so disabling the token later does not cut off devices that already joined.

Managing tokens

The Device tokens list (/devices/tokens) shows all your tokens. You can edit a token's nick and owner-verification settings, and disable a token so it can no longer be used to join devices — do this when a batch is done or when you suspect the secret leaked. Devices already registered are unaffected.

Security considerations

The token is a shared secret: every device in the batch carries the same value, and anyone holding it can join devices into your account.

• Treat it like a password — store it only in your factory provisioning pipeline, never in a repository.
• Use one token per batch/product line so a leak is contained and can be disabled without stopping other lines.
• Disable tokens you no longer provision with.

If a leaked token is a real risk for your fleet, add a second factor: enable owner verification on the token so a joining device must also prove possession of a TLS key against a certificate chain you registered. See TLS onboarding.