Help / IoT & embedded devices

Send files securely from IoT and embedded devices

IoT devices, PLCs, OT gateways, and single-board computers can send files through Paramant using only a static API key. They need no authenticator code (TOTP), no interactive login and no browser.

How machine authentication works

Every API call to Paramant authenticates with the X-Api-Key header containing your API key. The key starts with pgp_, followed by 64 hex characters, and identifies your account. An Authorization: Bearer header does not work for a pgp_ key: on these routes the relay only reads short-lived web dashboard session tokens (pst_) from it. Never put the key in the URL either; a request with ?k= is refused. For machines that is enough. Paramant only asks for a TOTP code when you sign in to the web dashboard.

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 example below or the Python SDK (pip install paramant-sdk). TLS 1.3 works out of the box.

ESP32 / ESP8266

Possible when the firmware has AES-256-GCM and HTTPS: mbedTLS in ESP-IDF has both. MicroPython has no AES-GCM, and we have no ready-made example for it. Let such a device send through a gateway or a Pi.

OT gateways

A gateway that makes outbound HTTPS calls and can run a script (Python 3 with cryptography) can use the example below.

Sending a file from a Linux device

There is no route that takes a readable file: the relay only ever receives encrypted bytes. So the device encrypts the file itself, uploads the sealed blob to POST /v2/inbound and gets a download_token back. From that it builds a link to /get, with the key after the #, so the relay never sees it. Python 3 with the cryptography package:

import os, json, base64, hashlib, struct, urllib.request from cryptography.hazmat.primitives.ciphers.aead import AESGCM API_KEY = os.environ["PARAMANT_API_KEY"] # pgp_... RELAY = "https://health.paramant.app" # the sector your key belongs to SECTOR = "health" PATH = "/var/log/sensor-log.csv" # one block: at most about 5 MB # 1. Seal the file on the device: [uint32-LE name length][name][bytes] name = os.path.basename(PATH).encode() plain = struct.pack("<I", len(name)) + name + open(PATH, "rb").read() key, iv = AESGCM.generate_key(bit_length=256), os.urandom(12) sealed = AESGCM(key).encrypt(iv, plain, None) # 2. Upload the ciphertext with its SHA-256 body = json.dumps({"hash": hashlib.sha256(sealed).hexdigest(), "payload": base64.b64encode(sealed).decode(), "ttl_ms": 3600000}).encode() req = urllib.request.Request(RELAY + "/v2/inbound", data=body, method="POST", headers={"X-Api-Key": API_KEY, "Content-Type": "application/json"}) token = json.load(urllib.request.urlopen(req))["download_token"] # 3. The link: the key travels after the #, the relay never sees it frag = base64.urlsafe_b64encode(key + iv).rstrip(b"=").decode() print(f"https://paramant.app/get?t={token}&r={SECTOR}#{frag}")

Give the link to the recipient through any channel. They open it in a browser; the page decrypts the file, and only then is it deleted on the relay. The link works once and expires after the ttl_ms the relay reports back (at most 1 hour on Community, 24 hours on Firm). One upload is one block of at most 5 MB; a larger file goes in several blocks, which the SDK does for you. The format is described in docs/api.md under "The share link".

Keep the API key in flash storage or an environment variable, 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. Here is how:

  1. Generate a new key in the dashboard.
  2. Push the new key to the device (OTA update, secure provisioning, or physical access).
  3. Check that the device sends 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

Request rate limits apply per IP address, not per API key. The nginx configuration in this repository puts general API traffic in a zone of 60 requests a minute, and uploads in a stricter one (nginx-selfhost.conf). The limit that is per key applies to downloads, not uploads: 50 downloads an hour on Community and 500 an hour on Firm (outbound_per_hour in relay/lib/tiers.js). Above that you get a 429 response. For frequent sensor data, combine readings into one file before uploading, rather than sending one file per measurement. A file can be up to 500 MB on every plan (file_mb in relay/lib/tiers.js). It travels in fixed blocks of 5 MB, so one upload call carries one block.

Common questions

My device gets a 401 on every request.
Check that the key is in the X-Api-Key header (for example X-Api-Key: pgp_...), not in Authorization: Bearer and not in the URL. Also check in the dashboard that the key has not been revoked.
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.