build 3.0.0 · aes-256-gcm / ml-kem-768 · eu/de · ram only
Help / IoT & embedded devices

Paramant on IoT and embedded devices.

IoT devices, PLCs, OT gateways, and single-board computers can send files through Paramant using only a static API key. No TOTP, no interactive login, no browser required.

How machine authentication works

Every API call to Paramant authenticates with an Authorization header containing your API key. The key is a 64-character hex string that identifies your account. For machine clients, this is sufficient — there is no TOTP prompt outside of the web dashboard login flow.

Generate a dedicated API key for each device or device class so you can revoke individual keys without affecting other integrations. Dashboard → API keys → Generate new key.

Supported device profiles

Raspberry Pi Zero / Zero 2

Full Linux stack. Use the Python SDK or curl directly. TLS 1.3 works out of the box.

ESP32 / ESP8266

Use the REST API over HTTPS. The Arduino and ESP-IDF HTTP clients both support the required headers.

OT gateways

Any gateway that can make outbound HTTPS calls — Tosibox, HMS Anybus, Ewon Flexy — can push files via the API.

Sending a file from a Linux device

Using curl (available on all Pi and gateway images):

curl -X POST https://api.paramant.app/v1/upload \ -H "Authorization: Bearer YOUR_API_KEY" \ -F "file=@/path/to/sensor-log.csv" \ -F "recipient=recipient@example.com" \ -F "ttl=3600"

The response contains a burn-on-read download URL you can pass to the recipient through any channel:

{"id":"abc123","url":"https://paramant.app/get/abc123","expires_at":"..."}

Sending a file from MicroPython (ESP32)

import urequests, uos API_KEY = "YOUR_API_KEY" FILE_PATH = "/sd/reading.bin" with open(FILE_PATH, "rb") as f: data = f.read() resp = urequests.post( "https://api.paramant.app/v1/upload", headers={"Authorization": "Bearer " + API_KEY, "Content-Type": "application/octet-stream", "X-Filename": "reading.bin", "X-Recipient": "ops@example.com"}, data=data ) print(resp.json()["url"])

Keep the API key in flash storage, not compiled into firmware. On ESP32 use NVS (Non-Volatile Storage) or a separate credentials partition so you can update the key without reflashing.

Key rotation on deployed devices

Rotate keys on a schedule, or immediately after a device is decommissioned, repaired, or handled by a third party. The rotation process:

  1. Generate a new key in the dashboard.
  2. Push the new key to the device (OTA update, secure provisioning, or physical access).
  3. Verify the device is sending successfully with the new key.
  4. Revoke the old key in the dashboard.

Revoke the old key only after confirming the new key works. A revoked key stops working immediately — there is no grace period.

Rate limits

The API accepts up to 60 uploads per minute per API key. For high-frequency sensor data, batch readings into a single file before uploading rather than sending one file per measurement. Files up to 5 GB are supported.

Common questions

My device gets a 401 on every request.
Check that the Authorization header is exactly Bearer YOUR_KEY with a space after "Bearer". Also verify the key has not been revoked in the dashboard.
TLS handshake fails on my embedded device.
Paramant requires TLS 1.2 or higher. Older firmware may use an outdated CA bundle. Update the device firmware or provision the current ISRG Root X1 certificate from Let's Encrypt.
Can I self-host the relay on a local network and reach it from devices?
Yes. Self-host a Paramant relay on your LAN and point devices at your internal hostname. See the self-hosting guide and install-pi.sh for a Raspberry Pi relay setup.

Related

API key vs TOTP

Why machine clients only need the API key.

Full API reference

All endpoints, parameters, and response schemas.