Device Provisioning

Nexigon Agent’s provisioning mode connects an unpaired device to a project using a short-lived provisioning token that can be redeemed at most once. The agent exchanges the token for a deployment token bound to that device and saves the credentials for subsequent connections.

We recommend using a dedicated provisioning image and disabling provisioning mode in the production image. The provisioning flow is:

1. Build, flash, and boot a dedicated provisioning image with provisioning mode enabled.
2. Generate a short-lived provisioning token in Nexigon for the intended project.
3. Send the token to the device to provision it.

Once the device connects, Nexigon supplies its production image and per-device configuration through the configured system update and device configuration workflows. The device then boots the production image with provisioning mode disabled.

Before You Start

You need:

• A project in Nexigon and permission to manage its tokens.
• A provisioning image with Nexigon Agent 0.6 or later, an executable fingerprint script, persistent storage for its credentials and TLS identity, and integrations for system updates and device configuration.
• A production image uploaded to a Nexigon repository and the configuration you want the device to apply.
• An HTTPS connection from the device to your Nexigon Hub instance.
• A machine that can reach the device on TCP port 6947.

The local provisioning endpoint uses HTTP and defaults to listening on all IPv4 interfaces. Provision devices on a trusted network and restrict access to that port until pairing is complete.

Build and Boot a Provisioning Image

Build a firmware image specifically for provisioning. Include the agent configuration below without hub-url or token, and enable provisioning:

fingerprint-script = "/usr/libexec/nexigon/nexigon-device-fingerprint"

[provisioning]
enabled = true

Use the path to your device’s fingerprint script. Its output must be unique to the device and remain stable across both images. The agent stores credentials under /var/lib/nexigon/agent and its TLS certificate and private key under /etc/nexigon/agent/ssl by default. Persist both directories when installing the production image.

Include an OTA integration that can install the production image and a configuration mechanism that can apply the values supplied by Nexigon. See the system update and device configuration guides for setup.

Flash the provisioning image and boot the device. Start the agent as a service on boot; it now waits for a provisioning token. You can check readiness from the machine that will provision it, replacing DEVICE_ADDRESS with the device’s hostname or IP address:

curl --fail-with-body http://DEVICE_ADDRESS:6947/

A ready agent returns {"status":"ready","endpoint":"/pair"}. See the provisioning configuration reference to change the bind address, port, fallback Hub endpoints, or device name.

Provision the Device

1. Open Devices in the intended project and choose Add Device.

2. In the Provisioning Token tab, copy the displayed provisioning command. The token is shown once, can be redeemed at most once, and expires after five minutes.

3. Replace DEVICE_ADDRESS in the command with the device’s hostname or IP address and run it from a machine that can reach the device:

   curl --fail-with-body --data "eu.nexigon.cloud,PAIRING_KEY" http://DEVICE_ADDRESS:6947/pair

   Use the complete value copied from your Hub in place of eu.nexigon.cloud,PAIRING_KEY. It contains the Hub domain, a comma, and the pairing key. The domain selects the HTTPS Hub instance where the agent redeems the key.

4. A successful response has "status":"paired" and includes the Hub URL and device ID. Choose Done in Nexigon and refresh the device list to confirm that the device is online.

If a token expires before you use it, choose Generate Another Token. Provision each additional device with a fresh token.

Deploy the Production Image and Configuration

After pairing, use Nexigon to assign the device’s production configuration and image. Set the desired configuration through device properties, then select the production release with Deploy Update. The integrations in the provisioning image retrieve and apply the configuration and install the production image.

Build the production image with provisioning disabled. Use the same fingerprint script and preserve the device’s credentials and TLS identity from the provisioning image:

fingerprint-script = "/usr/libexec/nexigon/nexigon-device-fingerprint"

[provisioning]
enabled = false

Keep hub-url and token omitted so the production agent reuses the saved credentials. With provisioning disabled, missing credentials cause startup to fail instead of reopening the provisioning listener.

After the update, confirm that the device is online with the expected production version and configuration.

Credentials After Provisioning

The agent stores the Hub URL and a device-bound deployment token in credentials.json under data-path, then closes the provisioning listener and connects to the Hub. Restarts reuse those credentials without another provisioning token. The Hub automatically accepts the new device’s first certificate; subsequent connections still use its certificate and fingerprint for device authentication.

Persist the credentials, certificate, and private key across system updates. Exclude this per-device state from images distributed to other devices.

Troubleshooting