Core Concepts

Workspace

The root organizational unit. Everything in IOTMER belongs to a workspace — devices, MQTT configuration, members, billing, and API keys. A user can be a member of multiple workspaces with different roles.

Device

A registered IoT endpoint. Each device has:

• A unique ID (ULID)
• Auto-generated MQTT credentials (username + password)
• Optional custom fields (typed key-value metadata)
• A current state (last reported payload)
• Assigned MQTT ACLs controlling publish/subscribe permissions

Device Template

A blueprint for a device model: capability tags, capability definitions (JSON envelope), default configuration, optional auto-generated device keys from a serial pattern, and default MQTT ACLs. Custom fields are workspace-defined and per-device, not configured inside the template editor.

MQTT Principal

A non-device MQTT identity (e.g. your backend application, a data pipeline, a monitoring tool). Principals have their own credentials and ACL sets, independent of any specific device.

Region

A geographic deployment of the IOTMER MQTT infrastructure. Workspaces can be active in multiple regions. Each region has its own MQTT endpoint.

Cloud MQTT vs Dedicated Cluster

	Cloud MQTT	Dedicated Cluster
Infrastructure	Shared, managed by IOTMER	Dedicated nodes, yours only
Setup time	Instant	Minutes (provisioned on-demand)
Isolation	Tenant-level ACLs	Full network isolation
Use case	Dev, small-medium fleets	Enterprise, compliance, custom config

API Key

A workspace-scoped token for machine-to-machine API access. API keys use the X-API-Key header and are an alternative to JWT tokens. Each key can have restricted permissions (RBAC).

Audit Log

An immutable, append-only log of all actions taken within a workspace — who did what, when. Useful for compliance and debugging.