Device identity & credentials

Every device on CORE-M has two identifiers and exactly one active credential type. Understanding the difference is the foundation for provisioning and for rotating credentials.

Two identifiers: device_id vs hardware_id

	device_id	hardware_id
What it is	Platform-assigned UUID	Manufacturer serial, MAC address, or other stable hardware identifier
Who sets it	CORE-M, at registration	You, from the hardware
Uniqueness	Globally unique	Unique within a tenant
Mutable?	Never	Treated as immutable — it is the idempotency anchor
Used for	All API paths and lookups (e.g. /api/v1/devices/{device_id})	De-duplication and idempotent (re-)provisioning

The device_id is what you use everywhere in the API. The hardware_id exists so the platform can recognize the same physical device across retries: registering or provisioning twice with the same hardware_id returns the existing device instead of creating a duplicate.

Caution

hardware_id is unique per tenant, not globally. Two different tenants may both have a device with hardware_id AA:BB:CC:00:11:22 — they are distinct devices. Within one tenant, a duplicate hardware_id on manual registration is rejected with ALREADY_EXISTS.

Credentials: how a device authenticates

Devices authenticate to CORE-M with one of three credential types. Pick the one that matches your protocol and threat model.

Credential	Issued by	Stored at rest as	Presented as
API key	Provisioning or CreateAPIKey; returned raw once	SHA-256 hash (raw key never stored)	Authorization: Bearer sk_live_… or X-API-Key: sk_live_…
PSK (pre-shared key)	Generated/assigned at provisioning, ≥ 32 bytes	Securely on the platform; provisioned to the device	DTLS PSK handshake (CoAP, LwM2M)
X.509 client cert	Your CA; the public cert is registered via RegisterDeviceCert	Only the SHA-256 fingerprint of the DER bytes	mTLS client certificate (MQTT, CoAP, LwM2M)

Caution

Dashboard users authenticate with Ed25519-signed JWTs (15-minute access token, 7-day refresh). Devices never use JWTs. A device presents an API key, a PSK, or an X.509 client certificate — nothing else. If you find yourself putting a device’s credential in a JWT, something is wrong.

API key

The most common device credential. Format:

sk_live_ + URL-safe encoding of 32 random bytes

The platform stores only a hash of the key. The raw value is returned exactly once — at provisioning or when you create the key — and cannot be retrieved again. If it is lost, rotate to a new one.

Present it on every request using either header:

Authorization: Bearer

POST /api/v1/devices/{device_id}/uplink HTTP/1.1
Host: api.kronoxdata.com
Authorization: Bearer sk_live_Zr8K2mQx...redacted...
Content-Type: application/json

{"kind":"telemetry","payload":"..."}

X-API-Key

POST /api/v1/devices/{device_id}/uplink HTTP/1.1
Host: api.kronoxdata.com
X-API-Key: sk_live_Zr8K2mQx...redacted...
Content-Type: application/json

{"kind":"telemetry","payload":"..."}

The auth middleware resolves the key to its tenant_id and device_id and injects them into the request context. The device never sends its own tenant_id — identity is derived from the credential, so a stolen key cannot impersonate another tenant’s device.

Tip

Use Authorization: Bearer where you can — it is the standard form and works with most off-the-shelf HTTP and MQTT client libraries. X-API-Key exists for clients that reserve the Authorization header for something else.

PSK (pre-shared key)

A symmetric secret of at least 32 bytes, used for the DTLS handshake on UDP transports. Best for constrained devices on CoAP or LwM2M where running a full certificate stack is too heavy. The PSK is generated or assigned during provisioning and burned into the device alongside its identity. Treat it like any other secret: it grants the same access as an API key.

X.509 client certificate

The strongest device credential, used for mutual TLS (mTLS) on MQTT, CoAP, and LwM2M. You issue the certificate from your own CA and register only the public certificate with the platform via RegisterDeviceCert (POST /api/v1/devices/{device_id}/certs). CORE-M parses the PEM server-side and stores only the SHA-256 fingerprint of the DER bytes — that fingerprint is the identity anchor for mTLS lookups.

Danger

Never send a device’s private key to the platform. RegisterDeviceCert accepts only the public certificate PEM. The private key stays on the device. Registering a private key would be a critical compromise.

To stop trusting a certificate, revoke it by fingerprint with RevokeDeviceCert (DELETE /api/v1/devices/certs/{fingerprint}). List a tenant’s certificates with ListDeviceCerts (GET /api/v1/devices/certs, optionally filtered by device_id).

Rotation and revocation

Credentials are not forever. Two operations keep them safe:

• Rotate — issue a fresh credential and retire the old one. For API keys, the new key is returned once; the old key keeps working for a configured overlap window so the device can switch over without downtime, then stops being accepted.
• Revoke — kill a credential immediately. Future requests using a revoked API key or certificate return UNAUTHENTICATED, and active protocol sessions authenticated by it are disconnected where the transport supports it.

Note

Rotate on a schedule; revoke on suspicion of compromise. Rotation has an overlap window so devices stay online; revocation is immediate and has no grace period.

Where credentials come from

You don’t mint credentials by hand — they are issued as part of a provisioning flow:

Provisioning by key claim Devices self-register in the field with a pre-shared key and receive an API key in the response.

Manual registration Register one device as an admin and receive its API key (shown once).

Bulk import Generate provisioning keys for a whole factory batch from a CSV.

Device profiles A credentials policy on a profile decides which credential type new devices get.