Skip to content

MQTT client management API (Mgmt add-on)

Automate portal MQTT clients (broker credentials that may publish, subscribe, or both) with the Mgmt REST API add-on.

Portal concepts and ACLs: MQTT clients. HTTP paths still use /api/v1/subscriber/publishers for compatibility.

Before you start

  1. Enable Mgmt REST API under Subscriptions in the portal.
  2. Create a REST API token in Settings — see REST API tokens.
  3. Use OpenAPI at /api/v1/subscriber/docs on your portal host.
PORTAL_ORIGIN="https://mqtt.ishareradio.com"
TOKEN="isr_mqtt_rest_<from-settings>"

Every request:

Authorization: Bearer isr_mqtt_rest_<token>

List MQTT clients

curl -sS "${PORTAL_ORIGIN}/api/v1/subscriber/publishers" \
  -H "Authorization: Bearer ${TOKEN}"

Each row includes client_id, topic (MQTT pattern hint), and pause state. Passwords are not returned from list.

Create an MQTT client

curl -sS -X POST "${PORTAL_ORIGIN}/api/v1/subscriber/publishers" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"label":"site-alpha-sensor","allow_subscribe":true}'

The create response includes device.password and publish_topic. Copy the password before you close the terminal — it is not returned on list or get.

History / Flux / REST always use the account-first platform path (UUID tenant id as the first topic segment):

{account_id}/{client_id}/<subtopic>

List responses include history_topic_prefix with that prefix for each device. The topic field is a live MQTT pattern hint (may differ for auto-enrolled vendor devices). For stored data and Grafana, use history_topic_prefix. Setup: MQTT clients — platform layout.

Pause, resume, remove

CLIENT_ID="pub-..."
curl -sS -X POST "${PORTAL_ORIGIN}/api/v1/subscriber/publishers/${CLIENT_ID}/pause" \
  -H "Authorization: Bearer ${TOKEN}"

curl -sS -X POST "${PORTAL_ORIGIN}/api/v1/subscriber/publishers/${CLIENT_ID}/resume" \
  -H "Authorization: Bearer ${TOKEN}"

curl -sS -X DELETE "${PORTAL_ORIGIN}/api/v1/subscriber/publishers/${CLIENT_ID}" \
  -H "Authorization: Bearer ${TOKEN}"

Rotate MQTT password

curl -sS -X POST "${PORTAL_ORIGIN}/api/v1/subscriber/publishers/${CLIENT_ID}/rotate-credentials" \
  -H "Authorization: Bearer ${TOKEN}"

Returns a new MQTT password in the response body. Copy it immediately; it is not shown again.

Read-only subscribers (listen)

To subscribe on {account_id}/# only (no device publish on vendor paths), use the separate read-only subscriber API — same Mgmt add-on and REST token:

Read-only subscribers