Give every device its own protected identity.

Provisioning sequence #

Use a product and batch to organize enrollment. Run enrollment from a trusted manufacturing system with a scoped, expiring service credential.

1. Create the device registry record and retain its stable UUID.
2. Create the device’s private key in protected storage and a certificate signing request whose common name is the device UUID.
3. Submit the CSR to /api/iot/v1/devices/{id}/credentials through the authorized manufacturing system.
4. Install the issued PEM certificate and trusted CA configuration. Apply the returned profile: SSID, realm, and authentication-server name.
5. Protect the separate device reporting token. Never substitute a manufacturer API token.
6. Remove temporary provisioning access and verify a test network attempt.

Reference provisioning commands #

Install the kit as described in the quickstart and select a product UUID. Run these commands in a trusted per-unit provisioning environment. Only the public CSR leaves local key storage; protect the returned bundle and securely install it on the corresponding unit.

# Requires Python >=3.10, OpenSSL, and a protected per-device directory.
umask 077
hotspotvu-connect enroll \
  --base-url "$HOTSPOTVU_API" \
  --product-id "$HOTSPOTVU_PRODUCT_ID" \
  --external-id SENSOR-0001 --name "Temperature sensor 1" \
  --directory /etc/hotspotvu-connect
hotspotvu-connect configure --directory /etc/hotspotvu-connect
# Output from enroll: {"device_id":"<UUID>","credentials_installed":true}
# The private key stays local. Only the CSR is submitted for signing.
# The partner token belongs only in this factory environment.
# Exclude it from the shipped device image.

• Install the kit and create a product →

Keep identities individual #

Do not copy a private key across a fleet or store a manufacturer’s API token on production devices. A compromised device should be revocable without replacing every device in the batch.

Protect enrollment records and avoid embedding secrets in support logs, QR codes, or public serial-number lookups.

Ownership and local network permission #

A manufacturing record does not grant a device permission at every customer site. The initial API supports explicit read-only provider delegation; customer ownership transfer is a separate capability outside this release.

A site operator allowing a connection grants network permission at that site. That action does not transfer the device’s ownership to the operator or the manufacturer.

Renewal and replacement #

The device can renew through /api/iot/v1/device/renew using an unexpired reporting token and proof of its associated certificate private key. The reference daemon begins renewal seven days before expiry; no manufacturer automation token is needed on the device.

A reporting token expires with its certificate. Older tokens and certificates remain valid across renewal until their own expiry or revocation, while the device is active and its account is not suspended. Install the returned bundle safely and keep the stable device identity.

Treat suspected key compromise as revocation and controlled replacement. Expired credentials need an authorized recovery process. Failed renewal must not disable certificate checks or bypass site permission.

Diagram and flow #

• DEVICE / PROTECTED STATION

  Generate the local key

  Create a UUID-bound CSR. Retain the private key in protected storage.

  CSR only → Enroll through the API
• TRUSTED BACKEND

  Enroll through the API

  Use scoped credentials and retain the stable registry identifier.

  Enroll scope → Issue the certificate
• CERTIFICATE SERVICE

  Issue the certificate

  Sign the CSR and return the certificate, trust and reporting bundle.

  Issued bundle → Install the profile
• PER-UNIT INSTALLATION

  Install the profile

  Install certificate, CA, server identity checks and device reporting token.

  Factory install → Power on and request
• CUSTOMER SITE

  Power on and request

  Authenticate with the installed identity. Wait for business approval.

Open full-size SVG ↗Download SVGMermaid source

Read the diagram description

• DEVICE / PROTECTED STATION — Generate the local key. Create a UUID-bound CSR. Retain the private key in protected storage.CSR only → Enroll through the API.
• TRUSTED BACKEND — Enroll through the API. Use scoped credentials and retain the stable registry identifier.Enroll scope → Issue the certificate.
• CERTIFICATE SERVICE — Issue the certificate. Sign the CSR and return the certificate, trust and reporting bundle.Issued bundle → Install the profile.
• PER-UNIT INSTALLATION — Install the profile. Install certificate, CA, server identity checks and device reporting token.Factory install → Power on and request.
• CUSTOMER SITE — Power on and request. Authenticate with the installed identity. Wait for business approval.