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
tsandvalueswhen 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: Bearerheader - 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-Deliveryid 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.
| Limit | Default | Applies to |
|---|---|---|
| Address limit | 120 requests a minute | Each calling IP address |
| Key limit | 1,000 calls a minute | Each API key |
| Commands | 10 a minute per device, 600 a minute per organisation | Commands to devices |
| MCP tools | 120 read and 20 write calls a minute | Each credential |
| Device HTTP body | Up to 64 KiB | Each 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.
Reference
API reference
Start building on Hermetry
Create an organisation, add a device and make your first API call.

