Skip to content

Read-only subscribers

The iShareRadio MQTT platform introduces Read-only subscribers are MQTT logins (sub-… usernames) for listen-only clients on platform topics:

{account_id}/#

Use them in Node-RED, MQTTX, or a partner integration that only needs to subscribe to live telemetry on the broker and not publish.

These are broker usernames and passwords — not REST API tokens. Do not put isr_mqtt_rest_… tokens in MQTT clients.

To connect devices or apps that publish or subscribe on the broker (including vendor wire paths), use MQTT clients instead.

When to use them

Need Use
Live MQTT subscribe on {account_id}/… (read-only) Read-only subscriber (this page)
Device or app publish / subscribe (including vendor topic trees) MQTT clients
History export, provisioning, billing automation REST API tokens
Portal UI or Grafana on stored history only Influx token or REST — optional

You do not need a read-only subscriber if you only use the portal, Grafana on history, or REST polling.

Cross-tenant access: another customer tenant reads your data via dataset / reseller offers, not read-only subscribers on your tenant. See Enterprise accounts and teams.

Prerequisites

  • Active MQTT SaaS base plan with read-only subscribers included (max_subscribers on the plan). Starter 10 includes 0; paid tiers scale up to 100 active passwords on Pro+ 1000 (12-month). See Subscriptions in the portal for your limit.
  • Your account ID (tenant id) from portal Settings → Profile.

Subscribe filter

Each password gets one subscribe filter (broker read ACL), assigned automatically:

{account_id}/#

All MQTT clients on your account appear under:

{account_id}/{client_id}/{subtopic}

Examples after ingest (platform paths — see MQTT clients):

Device client_id in portal Example subscribe topic
bench-sensor-1 {account_id}/bench-sensor-1/#
my-gateway {account_id}/my-gateway/telemetry/temperature

If devices publish on a vendor wire tree, paths are normalized to {account_id}/{client_id}/… after ingest once the layout is registered. See Built-in or vendor topic paths.

Portal and custom filters

The portal shows the filter when you create a password. You cannot edit it in the portal today. The Mgmt REST API uses the same tenant-wide filter; per-credential custom filters are not exposed yet.

Topic paths and shared fleet logins

Platform subscribe filters use {account_id}/{client_id}/…. Full setup (single vs shared credentials, what goes on the device): MQTT clients — platform layout.

  • {account_id} — tenant UUID from Settings. Not pub-….
  • {client_id} — the per-device id on that unit’s MQTT Clients row.
  • pub-… — id of a shared credential root; it is the MQTT username, not the {client_id} segment in topic paths.

Multiple read-only subscribers on one tenant share the same topic tree; separate passwords are for revocation and access control, not different paths.

Option 1 — Portal (Settings)

  1. Sign in at the MQTT portal.
  2. Open Settings → Read-only subscribers.
  3. Optional label, choose Expires (days or Never), click Create password.
  4. Copy username, password, and subscribe filter from the dialog (JSON, .env, or shell export) before you close it.

You can regenerate or revoke each row from the table. Regeneration invalidates the previous password immediately.

Use a different login than your MQTT client credentials so you can revoke listen-only access independently.

Option 2 — Mgmt REST API (automation)

Requires the Mgmt REST API add-on and a REST API token.

PORTAL_ORIGIN="https://mqtt.ishareradio.com"
TOKEN="isr_mqtt_rest_<paste-from-settings>"

Create (password in response only)

curl -sS -X POST "${PORTAL_ORIGIN}/api/v1/subscriber/subscriber-mqtt-passwords" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"label":"live-listener-1","never_expires":false,"expires_in_days":90}'

Example response — copy mqtt_password now:

{
  "credential": {
    "mqtt_username": "sub-550e8400-a1b2c3d4",
    "mqtt_password": "your-mqtt-password",
    "read_patterns": ["550e8400-e29b-41d4-a716-446655440000/#"]
  }
}

List, regenerate, revoke

OpenAPI: /api/v1/subscriber/docs — GET, POST …/regenerate, and DELETE on /api/v1/subscriber/subscriber-mqtt-passwords/{id}.

Active password count is capped by your base plan (up to 100).

Using credentials in MQTT clients

JSON / dialog field MQTT client setting
broker Host:port
use_tls Enable MQTTS in production
mqtt_username Username
mqtt_password Password
read_patterns Subscribe topic(s) — use as-is

Use the broker host, port, and TLS setting from the dialog (production typically uses MQTTS on port 443).

mosquitto_sub -h mqtt.ishareradio.com -p 443 \
  --cafile /etc/ssl/certs/ca-certificates.crt \
  -u 'sub-…' -P 'your-mqtt-password' \
  -i 'my-listener-01' \
  -t 'YOUR-ACCOUNT-UUID/#' \
  -v

Troubleshooting

Issue What to check
Connection refused Host and port match the dialog; TLS on/off matches use_tls
Auth failure Wrong password; regenerate if lost
No messages MQTT clients paused; nothing under {account_id}/…; fanout disabled
Need to publish or use vendor wire topics MQTT clients
HTTP 403 on REST Mgmt add-on; valid REST token