Provisioning by key claim

Key claim is the flow for self-provisioning at scale. Instead of registering each device by hand, you (or your contract manufacturer) burn a shared provisioning key into a batch of devices. On first boot, each device calls POST /api/v1/provision with that key, and the platform creates the device and returns its credentials. No operator is in the loop at claim time.

This is the right flow when devices come off a line and must come online on their own. For one-off devices, manual registration is simpler.

Step 1 — Create a provisioning template / key

A tenant admin creates a provisioning template (and the key it issues) ahead of time. The template scopes what the key may do:

Field	Purpose
Profile reference	The device profile new devices inherit (tags, config, anchoring policy, telemetry schema, …)
Allowed hardware_id pattern	Restricts which hardware IDs may claim with this key
Expiry	UTC instant after which the key is rejected (no expiry if unset)
One-time flag	If set, the key is marked used after a successful claim
Credential type	Which credential new devices receive (API key, PSK, or cert)
Default groups	Groups every device claimed with this key joins

The key is bound to one tenant. The provisioned device’s tenant is always derived from the key — never from anything the device sends.

Note

The platform stores only the SHA-256 hash of the provisioning key (along with its tenant, name, status, and expiry). The raw key is shown once on creation; distribute it securely to the factory and treat it like the secret it is.

Step 2 — The device claims its identity

On first boot the device sends its raw provisioning key, a human-readable name, and its stable hardware_id to POST /api/v1/provision.

POST /api/v1/provision HTTP/1.1
Host: api.kronoxdata.com
Content-Type: application/json

{
  "provision_key": "pk_factory_7Qx2mZr8K...redacted...",
  "device_name": "Cold Store Sensor 014",
  "hardware_id": "AA:BB:CC:00:11:22"
}

Note

There is no tenant_id field in this request, by design. The tenant is derived from the validated key. A device cannot ask to be placed in a tenant — it can only prove which tenant’s key it holds.

The same call over curl:

curl -sS -X POST https://api.kronoxdata.com/api/v1/provision \
  -H "Content-Type: application/json" \
  -d '{
    "provision_key": "pk_factory_7Qx2mZr8K...redacted...",
    "device_name": "Cold Store Sensor 014",
    "hardware_id": "AA:BB:CC:00:11:22"
  }'

Successful first claim

A brand-new device gets back its platform device_id and a freshly minted api_key:

{
  "device_id": "8f1c0b7e-3d2a-4f56-9a10-2c4e6f8b1d33",
  "api_key": "sk_live_Zr8K2mQx...redacted..."
}

Danger

The api_key is returned exactly once. Persist it on the device immediately — the platform stores only a hash and cannot show it again. If the device loses it, you must rotate to a new key.

The device now drops the provisioning key and authenticates all future requests with sk_live_…. See credentials for the auth headers.

Idempotent re-claim

If a device with the same hardware_id already exists in the tenant, the call is idempotent: it returns the existing device_id and an empty api_key.

{
  "device_id": "8f1c0b7e-3d2a-4f56-9a10-2c4e6f8b1d33",
  "api_key": ""
}

An empty api_key is not an error — it is the platform saying “I already know this device; keep using the key you were issued before.” No duplicate device is created, no second key is minted, and no device.provisioned event is emitted. Devices must therefore store their first-issued API key durably and not depend on getting a new one on re-boot.

Tip

Design your firmware so re-claiming is safe: try to provision, and if the response api_key is empty, fall back to the key already in secure storage. This makes the boot path resilient to retries, flash wipes that preserve the key, and network hiccups.

The full claim flow

sequenceDiagram
  autonumber
  participant Dev as Device
  participant GW as Gateway / device-link
  participant Reg as Device registry
  participant Auth as Auth service

  Dev->>GW: POST /api/v1/provision<br/>{provision_key, device_name, hardware_id}
  GW->>GW: SHA-256(provision_key)
  GW->>GW: Look up key by hash,<br/>constant-time compare,<br/>check status + expiry
  Note over GW: Invalid / disabled / expired →<br/>PermissionDenied (uniform)
  GW->>Reg: CreateDevice(tenant_from_key, name, hardware_id)
  alt New hardware_id
    Reg-->>GW: device_id (created)
    GW->>Auth: MintAPIKey(tenant, device_id)
    Auth-->>GW: sk_live_… (raw, once)
    GW-->>Dev: {device_id, api_key}
    GW--)Reg: publish device.provisioned event
  else Existing hardware_id (idempotent)
    Reg-->>GW: device_id (existing)
    GW-->>Dev: {device_id, api_key: ""}
  end

Security properties

Caution

The claim path is built so a leaked or guessed key reveals as little as possible:

• The raw key is never persisted. Only its SHA-256 hash is stored, and the raw key is never logged.
• Constant-time comparison. The stored hash is compared against a freshly computed hash of the presented key using a constant-time comparison, so timing cannot be used to recover the key.
• Tenant derived from the key. The device’s tenant comes only from the validated key — never from any client-supplied field. A device cannot choose its tenant.
• Uniform error. Unknown, disabled, and expired keys all return the same PermissionDenied (“invalid provisioning key”). Callers cannot tell the three states apart, so valid keys cannot be enumerated.
• Idempotent, single-issue credentials. A re-claim never mints a second key, preventing accidental credential sprawl from retries.

Related

Device profiles The defaults and policies a claimed device inherits via the template's profile reference.

Device identity & credentials What the returned API key is, how to present it, and how to rotate it.

Bulk import Generate provisioning keys for a whole factory batch, then claim per this flow.

Manual registration Register a single device directly when self-provisioning is overkill.