LoRaWAN API

This page lists the REST routes of Hermetry’s LoRaWAN network server in one place. Each topic has a page in the LoRaWAN section with the full field meanings; this page links to them. Paths are under https://<your host>/tenant/<tenantId>. Every answer of these routes is sent with Cache-Control: no-store.

Permissions

Permission	Default role	Allows
iot_lorawan.gateways.read	User	Read gateways and the network server address
iot_lorawan.gateways.manage	Admin	Add, edit, disable and delete gateways, rotate their tokens
iot_lorawan.devices.read	User	Read LoRaWAN devices, profile settings and pairing
iot_lorawan.devices.manage	Admin	Add, edit and delete devices, set keys, end sessions, pairing
iot_lorawan.keys.read	Admin	Reveal a device’s AppKey
iot_lorawan.frames.read	User	Read the live frames log

Setup

GET /api/iot/lorawan/setup (gateways read) answers the network server address and the discovery address a Basics Station gateway needs, whether a tc.trust file is offered, and the region. Nothing secret. See Your network server address.

Gateways

Method	Path	Permission	Does
GET	/api/iot/lorawan/gateways	gateways read	List: { data, total, canManage }
POST	/api/iot/lorawan/gateways	gateways manage	Add a Basics Station gateway: { gateway, token, stationConfig }
GET	/api/iot/lorawan/gateways/{gatewayId}	gateways read	{ gateway, live, devicesHeard }
PATCH	/api/iot/lorawan/gateways/{gatewayId}	gateways manage	name, status (ACTIVE or DISABLED), latitude, longitude, altitude
DELETE	/api/iot/lorawan/gateways/{gatewayId}	gateways manage	Close its connection, release its EUI, remove it
POST	/api/iot/lorawan/gateways/{gatewayId}/credentials	gateways manage	New token: { gateway, token, stationConfig }

The list takes page (from 0), pageSize, search, sort (name, eui, protocol, mode, status, region, lastSeen, createdAt; default name:asc) and the filters protocol, mode, status, region, deviceId, online.

Create body:

{ "eui": "AA555A0000000101", "name": "Roof gateway", "latitude": 41.0151, "longitude": 28.9795, "altitude": 45 }

eui is required (16 hexadecimal characters; dashes, colons and spaces are ignored), name 1 to 128 characters. The protocol defaults to Basics Station, the mode to cloud and the region to EU868, the only region offered. The token is in this answer only. Licensed routers are not added here: they switch to cloud mode on their own panel, see Licensed routers as LoRaWAN gateways. Rotating the token of a gateway without one is refused: “This gateway does not use a token.” See Add a gateway and Gateway credentials, disable and delete.

Devices

Method	Path	Permission	Does
GET	/api/iot/lorawan/devices	devices read	List: { data, total, canManage }
POST	/api/iot/lorawan/devices	devices manage	Add an OTAA or ABP device (201 { device })
GET	/api/iot/lorawan/devices/{deviceId}	devices read	{ device }: the record and its live session, never a key
PATCH	/api/iot/lorawan/devices/{deviceId}	devices manage	name, joinEui, appKey, macVersion, class, anyJoinEui, codecId; for ABP devAddr, nwkSKey, appSKey together
DELETE	/api/iot/lorawan/devices/{deviceId}	devices manage	Remove the device, its sessions and its DevEUI claim
POST	/api/iot/lorawan/devices/{deviceId}/key	keys read	Reveal the AppKey: { appKey }; every call is audited
DELETE	/api/iot/lorawan/devices/{deviceId}/session	devices manage	End the session; the device must join again
DELETE	/api/iot/lorawan/devices/{deviceId}/counters	devices manage	Reset an ABP device’s frame counters
POST	/api/iot/lorawan/devices/{deviceId}/approve	devices manage	Approve a device that pairing mode added

The list takes page (from 0), pageSize, search, sort (name, devEui, macVersion, class, createdAt; default createdAt:desc), and the filters macVersion, class and joinState (joined, refused, never).

Add an OTAA device

{
  "name": "Cold room 3",
  "devEui": "1122334455667701",
  "appKey": "2B7E151628AED2A6ABF7158809CF4F3C",
  "joinEui": "0000000000000000",
  "macVersion": "1.0.3",
  "class": "A",
  "codecId": "auto",
  "anyJoinEui": false
}

Only name, devEui and appKey are required; the rest shows the defaults. macVersion is 1.0.2, 1.0.3 or 1.0.4; class is A or C. The answer never carries the AppKey, only hasAppKey: true. A new AppKey resets the device’s join nonce history. See Add an OTAA device.

Add an ABP device

{
  "name": "Water meter 12",
  "activation": "ABP",
  "devEui": "1122334455667712",
  "devAddr": "26011F3A",
  "nwkSKey": "…32 hexadecimal characters…",
  "appSKey": "…32 hexadecimal characters…"
}

An ABP body with an appKey, or an OTAA body with session keys, is refused. See Add an ABP device.

Profile settings and pairing

Method	Path	Permission	Does
GET	/api/iot/lorawan/profiles/{profileId}/settings	devices read	{ settings } of the profile’s LoRaWAN tab
PUT	/api/iot/lorawan/profiles/{profileId}/settings	devices manage	Change them; sharedAppKey is write-only
GET	/api/iot/lorawan/profiles/{profileId}/pairing	devices read	{ pairing }: the window and the devices it added
POST	/api/iot/lorawan/profiles/{profileId}/pairing	devices manage	{ "minutes": 1–120 } opens the window, or moves its end
DELETE	/api/iot/lorawan/profiles/{profileId}/pairing	devices manage	Close the window now

The settings fields, including those only the API sets, are listed in LoRaWAN device profiles. Pairing is explained in Pairing mode and Approving paired devices.

Frames log

GET /api/iot/lorawan/frames?deviceId={deviceId}&gatewayId={gatewayId}&limit=200

{ frames }: your recent frames, newest first, from a short live log that is not stored. A dropped frame of a device of another organisation shows only its reason. See The frames log.

Downlinks and codecs

• Application downlinks are commands with the method lora.downlink: { "fPort": 1–223, "data": "<hex or base64>", "confirmed": false }, sent with the Commands API. See Downlinks.
• Codecs have their own routes: Codec API.

Refusals

LoRaWAN refusals carry plain messages, for example “A Basics Station gateway always runs in cloud mode.”, “This gateway does not use a token.” or a key that is not 32 hexadecimal characters. Field rules that fail are a 400 with issues. See Errors and rate limits.