Skip to main content

B2B Tier 1 — Shared Key

Pre-provisioned onboarding with a Glaze-issued bootstrap key and symmetric MQTT credentials retrieved via GET /get_settings.

In this flow, devices are pre-provisioned during manufacturing or deployment — no customer app is involved. The manufacturer or deployment engineer calls the provisioning API to bind devices to a tenant. When the device first connects to the network, it self-onboards by calling /get_settings with its bootstrap key and then connects to the broker with username/password.

When to use this flow

Use this flow for B2B/industrial devices (connected chargers, commercial appliances, industrial sensors) where:

  • A customer app is not part of the deployment model
  • Devices are provisioned during manufacturing or by a field deployment team
  • The manufacturer has no PKI
  • mTLS is not a regulatory requirement (move to Tier 2 / Tier 3 if certificates are needed)

Prerequisites​

Manufacturer / Deployer:

  • Receive a bootstrap key from Glaze per enrollment group
  • Flash each device with: device_id, bootstrap_key, onboarding URL, Glaze Root CA certificate (HTTPS trust)
  • Call POST /api/devices/register + POST /api/provisioning for each device during manufacturing or deployment (or run a bulk pipeline against a device manifest)

Platform:

  • Beacon Tower onboarding service deployed and reachable from the device's network
  • Glaze CA operational (HTTPS server certs only — no client certs in this tier)
  • The enrollment group has bootstrap keys generated (POST /api/enrollment-groups/{id}/keys/generate) and a populated response_template

Device hardware:

  • Network connectivity (Ethernet, cellular, or pre-configured WiFi)
  • TLS client capable of HTTP Basic Auth and JSON parsing
  • Persistent storage for the operational MQTT credentials

Sequence Diagram​

Flow Walkthrough​

Step 1: Pre-Provision During Manufacturing / Deployment​

The manufacturer or deployment team registers and provisions devices in bulk — either during production or as part of a site deployment. Two HTTP calls per device:

# 1a. Register the device — creates the onboarding-side row
curl -X POST https://<onboarding-host>/api/devices/register \
  -H "Authorization: Bearer $DEPLOY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "device_id": "charger-unit-0042",
    "attestation_type": "shared_key",
    "enrollment_group_id": "<enrollment-group-uuid>"
  }'

# 1b. Provision — drives the orchestrator chain
curl -X POST https://<onboarding-host>/api/provisioning \
  -H "Authorization: Bearer $DEPLOY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "device_id": "charger-unit-0042",
    "enrollment_group_id": "<enrollment-group-uuid>"
  }'
# 201 Created
# {"deviceId":"charger-unit-0042","created":true}

The enrollment group defines the tenant, attestation type, provider configuration, and the device-facing response_template. For bulk deployments, this is part of an automated pipeline iterating over a manifest of device IDs.

Each device is flashed with its bootstrap key, the onboarding URL, the Glaze Root CA (for HTTPS server cert validation), and network configuration (static IP, cellular APN, or pre-configured WiFi SSID/password).

Step 2: Device Fetches Credentials​

When the device powers on at the deployment site, it connects to the network and calls onboarding's /get_settings endpoint with HTTP Basic Auth (device_id:bootstrap_key) over HTTPS:

GET /get_settings HTTP/1.1
Host: <onboarding-host>
Authorization: Basic Y2hhcmdlci11bml0LTAwNDI6Ym9vdHN0cmFwLWtleQ==

Onboarding validates the bootstrap key, resolves the device's MQTT credentials from the provider, and renders them through the enrollment group's response_template. The default response shape is:

{
  "deviceId": "charger-unit-0042",
  "enrollmentGroupId": "<uuid>",
  "brokerUrl": "broker.example.com",
  "brokerPort": 1883,
  "primaryKey": "<symmetric key A>",
  "secondaryKey": "<symmetric key B>"
}

A successful /get_settings transitions the device state on the onboarding side from "provisioned" → "configured". No human interaction is needed — the device completes onboarding autonomously on first boot.

Step 3: Connect to Broker​

The device opens a plain TCP MQTT connection (port 1883) using username = device_id and password = primaryKey. The broker verifies the credentials against the provider's MQTT user store and grants access to the device's topic namespace.

Step 4: Key Rotation (optional)​

If the primary key is rotated or compromised, the device falls back to secondaryKey (retrieved at step 2). To generate fresh keys, the deployment team calls POST /api/enrollment-groups/{id}/keys/generate (admin scope) and reflashes the new bootstrap key onto the device fleet.

Lifecycle Operations​

The four steps above cover the device-driven happy path. The operations below cover the rest of the lifecycle — admin-driven (revoke, disable, approval gating) and device-driven recovery from states the happy path cannot fix on its own (session loss, shard rotation).

Session-loss recovery / shard rotation — POST /reenroll​

Used when the device's MQTT session is broken — broker refused CONNECT, MQTT 5 reason 0x82 (session-taken-over) / 0x9C (use-another-server), or the device woke up after a fleet rebalance and its provider shard moved.

Distinct from Step 2's /get_settings: /get_settings is "I just provisioned, give me everything." /reenroll is "I'm already provisioned, tell me where to connect and rotate my MQTT keys if the routing changed."

POST /reenroll
Authorization: Basic <base64(device_id:bootstrap_key)>
StatusMeaning
200Existing routing is healthy — idempotent fast path. Device reconnects with current credentials.
201Routing was refreshed (shard rotation). Response carries new primaryKey + secondaryKey; device must persist them and replace its current primaryKey.
202Admin approval required — retry after the indicated interval (see below).
403The enrollment group's re-enrollment policy denied the request.
409Re-enroll not supported for the routing target type.
503Provider unavailable — retry with backoff.

Rate-limited per device.

Admin-gated approval​

An enrollment group can be configured to require an admin decision on every re-enrollment. When that gate is active, the device's /reenroll call returns 202 Accepted with a Retry-After header instead of rotated credentials. The device keeps retrying on that cadence until an admin makes a decision:

  1. Admin reads the parked request: GET /api/devices/{deviceRecordId}/pending-reenrollment.
  2. Admin approves or rejects:
    • POST /api/devices/{deviceRecordId}/pending-reenrollment/approve — next device retry succeeds.
    • POST /api/devices/{deviceRecordId}/pending-reenrollment/reject — next device retry returns 403 until the parked request expires (group-configured TTL).

Use this for fleets where every re-enrollment must trace back to a human decision.

Revoke a device​

Two operations, both admin-only (JWT). Run them together for a full revoke:

EndpointEffect
DELETE /api/devices/{deviceId}Soft-deletes the onboarding device record. Subsequent get_settings / reenroll calls fail.
POST /api/devices/{deviceId}/delete-provider-clientTells the provider to evict the MQTT user + ACL rules. Returns 202 Accepted once queued. After this returns, the broker rejects the device's existing MQTT credentials.

Order matters only for which call returns last; both are idempotent. After a revoke the bootstrap key on the device is useless — the soft-delete makes /get_settings fail before key validation.

Disable / re-enable​

Soft-delete is the disable mechanism. Restore brings the device back:

EndpointEffect
DELETE /api/devices/{deviceId}Soft-delete (same as revoke). Device cannot fetch settings or re-enrol.
POST /api/devices/{deviceId}/restoreUndoes the soft-delete. The device's bootstrap key works for /get_settings again; the previously issued primaryKey may or may not still be live at the provider — call /reenroll on first reconnect to be sure.
POST /api/devices/bulk-delete / bulk-restoreBatch variants (NDJSON body).

Security Considerations​

  • Symmetric credentials, not certificates — MQTT auth is username/password with the device's primaryKey. No mTLS, no per-device certificate identity. Trade-off in exchange for the lowest device-side complexity.
  • Bootstrap key is enrollment-group-scoped — a single bootstrap key may authorise /get_settings for every device in the enrollment group. Treat it as a batch secret. For per-device identity guarantees use Tier 2 (OTP + per-device cert) or Tier 3 (birth-cert + per-device EST cert).
  • Pre-provisioned — The device is bound to a tenant before leaving the factory or deployment site. There is no window where an unprovisioned device could be claimed by an unauthorised party.
  • HTTPS-only for /get_settings — the bootstrap key travels in an Authorization: Basic header; the device MUST validate the server's TLS certificate against the Glaze Root CA before sending the header.
  • No app dependency — The onboarding process is fully autonomous. No mobile app, BLE pairing, or SoftAP required.

Next Steps​