How the platform works

Overview

Devices talk MQTT to the broker. Everything after the broker is ours to run: ingestion writes to a durable stream, a processor commits each event to the database, and the API serves history and live updates to the dashboard.

device  --MQTT/TLS :8883-->  broker  -->  ingestion  -->  stream
                                                              |
browser  <--SSE--  API  <--  time-series DB  <--  processor <-+

Connectivity

The endpoint is TLS only and uses a publicly trusted certificate, so a standard CA bundle is enough. Each credential belongs to exactly one device, and the broker enforces what it may do.

Host

mqtt.iotaps.com

Port

8883, TLS 1.2 or newer

Protocol

MQTT 5 or 3.1.1, QoS 0 or 1

Client ID

The device ID; anything else is refused

Username / password

Credential ID and its one-time secret

Topic

v1/{org}/{project}/{device}/telemetry, publish only

Credentials

Up to five active per device, for rotation without downtime

Ingestion

A message passes four checkpoints. We only claim durability from a checkpoint we can show in metrics.

1. Broker-acknowledged

   The broker accepted the publish. Your device gets its PUBACK here.

2. Platform-accepted

   The envelope is valid and fsynced to the stream. Only then is the broker delivery acknowledged.

3. Persisted

   One transaction stores the event, latest state, usage, and an outbox row.

4. Processed

   Work after the commit, such as live updates, reads the outbox.

Retries

Device ID plus message_id is deduplicated for seven days, so a redelivered or resent message is stored once.

Rejections

Invalid payloads get a stable reason code, such as invalid_json or payload_too_large, and are listed on the device page with the start of the payload.

Dead letters

An event that passed validation but cannot be stored is set aside with its error for an operator to replay or discard. It is not dropped.

History

Telemetry is stored in TimescaleDB. Short ranges return raw points; longer ranges return server-side buckets with the average, minimum, and maximum, so a 30-day chart is still one small response.

Raw points

Ranges up to 24 hours, at most 10,000 points

Aggregates

Ranges up to 30 days, min / avg / max per bucket

Latest state

Last value per metric, each with its own timestamp

Timestamps

Device time (sent_at) and receive time are both kept

Retention

30 days during the beta

Live updates

An open device page receives committed events over Server-Sent Events, on the same HTTPS connection as the rest of the app. The stream rechecks your access every few seconds, so removing a member also ends their live view.

event: telemetry
data: {"device_id":"01a10e7f…","metrics":{"temperature_c":23.4}}

: keepalive

event: telemetry
data: {"device_id":"01a10e7f…","metrics":{"temperature_c":23.5}}

Teams and roles

Each organization is a separate tenant. Projects group devices, and four roles decide what a member can do. People sign in through OpenID Connect; IoTAPS does not store passwords.

Operations

Usage counters

Persisted messages and bytes, suppressed duplicates, and rejected messages, per organization and project, per day.

Audit log

Who created a device, revoked a credential, invited a member, or changed a role, and when.

Service metrics

Accepted, persisted, and rejected counts, stream lag, and end-to-end latency for each pipeline stage. We watch these; they are not exposed to customers yet.

Security

TLS

MQTT on 8883 and the web on HTTPS, with certificates renewed automatically.

Device secrets

High-entropy, shown once, stored as hashes.

Broker ACLs

Deny by default. A device may publish to its own topic and nothing else.

Tenant isolation

API authorization on every request, plus row-level security in the database.

Service accounts

Separate database roles and network policies per service.

Sessions

Server-side sessions in Secure, HttpOnly cookies, with CSRF protection.

Found a problem? Email hello@iotaps.com with “Security” in the subject.

Roadmap

No dates. Items move left when they ship.