New: the AI firewall watches the whole platform and explains each incident in plain words. See how it works

Developers

MQTT and HTTPS device APIs, the REST API with scoped keys, signed webhooks, rate limits and MCP servers for AI assistants.

Developers

Build on Hermetry

Connect devices over MQTT or HTTPS, work with your organisation through the REST API, react to events with signed webhooks, and let AI assistants read your data over MCP.

Four ways in

One platform, four interfaces

Devices use the device API. Your systems use the REST API and webhooks. AI assistants use MCP. Never put an API key on a device, or a device token in an integration.

Device API

Devices send data and receive commands over MQTT or HTTPS. They log in with a device token, an MQTT user name and password, or a certificate.

REST API

Your ERP, MES, ticket system or script calls Hermetry with an API key that holds only the permissions you choose.

Webhooks

Hermetry calls your system when something happens: a device going offline, an alarm opening, a command ending.

MCP servers

An AI assistant that supports MCP calls Hermetry’s tools with an API key or a sign-in, and never more than that person may do.

Device API

Send your first reading

Over MQTT the device keeps one connection open. Over HTTPS it sends one request per message. The payloads are the same.

MQTT

  • MQTT 3.1.1, TLS on port 8883 (TLS 1.2 or later), to the host on the device’s Connection details card
  • Username: the device access token, password empty
  • Topics start with v1/; use QoS 1
  • A reading is a flat JSON object, or ts and values when the device knows the time
CONNECT   port 8883 (TLS)
          username: <device access token>, password: empty
SUBSCRIBE v1/attributes/set   (QoS 1)
SUBSCRIBE v1/attributes/res/+ (QoS 1)
SUBSCRIBE v1/rpc/req/+        (QoS 1)
PUBLISH   v1/attributes/req/1 {}
PUBLISH   v1/telemetry        {"temperature": 21.5, "humidity": 40}
{"temperature": 21.5, "humidity": 40, "door_open": false}

{"ts": 1759572000000, "values": {"temperature": 21.5, "humidity": 40}}

HTTPS

  • One POST per message, with the token in an Authorization: Bearer header
  • The same payload forms and key rules as MQTT, up to 64 KiB
  • Commands wait in a long poll of up to 60 seconds
  • Battery devices that wake, send and sleep fit best
curl -X POST 'https://<your-host>/api/v1/telemetry' \
  -H 'Authorization: Bearer <device access token>' \
  -H 'Content-Type: application/json' \
  -d '{"ts":1759572000000,"values":{"temperature":21.5,"humidity":40}}'
curl -X GET 'https://<your-host>/api/v1/rpc?timeout=20000' \
  -H 'Authorization: Bearer <device access token>'

REST API

Call the API with a scoped key

An API key acts as the member who created it, limited to the permissions you tick for it. There is no token exchange: the key is sent on every call.

  • Keys look like sk_live_… and are shown once
  • Permissions are chosen one module at a time, never more than your own
  • Every key expires: 90 days by default, at most a year
  • An IP allowlist of up to 100 subnets limits where a key works
  • Paths are under your organisation: /tenant/<tenantId>/api/…
curl "https://<your host>/tenant/<tenantId>/api/iot/devices" \
  -H "Authorization: Bearer sk_live_…"
GET /tenant/{tenantId}/api/telemetry/latest?kind=iot_device&entityId={deviceId}&keys=temperature,humidity

Webhooks

React to events, and check they came from us

Each delivery is a POST with the event in the body and a signature in the headers. Verify X-Webhook-Signature-V2 with your signing secret before you trust the body.

  • HTTPS addresses only, with up to 20 custom headers of your own
  • Event filters deliver only the events whose payload matches
  • The same X-Webhook-Delivery id on every retry, so you can drop duplicates
  • CloudEvents 1.0 instead of the default envelope, if you prefer it
{
  "webhookId": "…",
  "tenantId": "…",
  "event": "device.disconnected",
  "createdAt": "2026-11-03T12:00:30.000Z",
  "data": { "deviceId": "…", "name": "router-17", "reason": "timeout" }
}
import crypto from 'crypto';

function verifyWebhook(body: string, timestamp: string, signatureV2: string, secret: string): boolean {
  const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(`${timestamp}.${body}`).digest('hex');
  // Reject deliveries older than 5 minutes.
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
  const a = Buffer.from(expected);
  const b = Buffer.from(signatureV2);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Limits

Limits to plan for

A limit answers 429 with a Retry-After header. Wait that long, back off on repeats, and never retry a 400, 401, 403, 404 or 422 unchanged.

LimitDefaultApplies to
Address limit120 requests a minuteEach calling IP address
Key limit1,000 calls a minuteEach API key
Commands10 a minute per device, 600 a minute per organisationCommands to devices
MCP tools120 read and 20 write calls a minuteEach credential
Device HTTP bodyUp to 64 KiBEach device message

AI assistants

Connect an AI assistant over MCP

Each module has its own MCP server under your workspace’s address. MCP is off until an administrator switches it on, and an assistant sees only the tools its person may use.

  • Devices, readings and dashboards: read only
  • Alarms: acknowledge one at once; clearing one waits for a second person
  • Answers are capped at 10 seconds and 256 KiB
  • Device credentials, tokens and keys are never returned
https://<your host>/tenant/<tenantId>/api/mcp/iot_device
https://<your host>/tenant/<tenantId>/api/mcp/telemetry
https://<your host>/tenant/<tenantId>/api/mcp/iot_alarm
https://<your host>/tenant/<tenantId>/api/mcp/dashboard

Scale and extend

When one device becomes a thousand

Import from CSV

Add hundreds of devices from a file. Every import is checked first, applied after review and can be undone.

Claiming and provisioning

Devices claimed with a code, or registered on first connection through a provisioning session.

Signed firmware in waves

You sign images in your own pipeline and register only public keys. Rollouts go out in waves.

Your own codecs

Decode a LoRaWAN sensor the library does not cover with a codec you publish: a JSON table, never a script.

Script block

When the ready blocks of a flow are not enough, run your own JavaScript on each message.

Your own widgets

Save a configured card as a widget, or author widgets from an HTML template with their own settings form.

Start building on Hermetry

Create an organisation, add a device and make your first API call.