Skip to content

REST API tokens

REST API tokens (isr_mqtt_rest_…) authenticate HTTP calls to /api/v1/subscriber/…. They are for scripts, CI/CD, and integrations — not for MQTT clients.

Use Read-only subscribers for live MQTT subscribe.

Create a token (portal)

  1. Subscribe to a base plan.
  2. Open Settings → REST API tokens.
  3. Optional label, choose Expires in (days), click Create token.
  4. Copy the token from the dialog before you close it — the portal does not show it again later.

You can keep up to 10 active tokens. Revoke unused tokens before creating new ones.

Refresh / rotate a token

Stored tokens cannot be displayed again. To rotate:

  1. Settings → REST API tokens → Revoke the old token.
  2. Create token again with a new label or expiry.

Update every script, secret store, and CI variable that used the old value.

Use tokens with add-ons

The same isr_mqtt_rest_… token is sent on every request:

Authorization: Bearer isr_mqtt_rest_<your-token>

Which routes work depends on add-ons on your account (not on the token label):

Add-on Example endpoints
Programmatic History Download GET /api/v1/subscriber/history
Live REST API GET /api/v1/subscriber/publishers/live
Mgmt REST API GET/POST/DELETE /api/v1/subscriber/publishers, POST /api/v1/subscriber/subscriber-mqtt-passwords, …

Example (Mgmt — list MQTT clients):

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

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

Example (Mgmt — create subscriber MQTT password):

curl -sS -X POST "${PORTAL_ORIGIN}/api/v1/subscriber/subscriber-mqtt-passwords" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"label":"automation","expires_in_days":30}'

See Read-only subscribers for the full JSON response and MQTT client mapping.

Rate limits and security

  • Each token is capped at 5000 requests / hour (per token).
  • Treat tokens like passwords: store in a secret manager, not in git.
  • Mgmt tokens can manage MQTT clients; scope automation tokens narrowly (separate labels per integration) and revoke when staff or contractors change.

OpenAPI

Interactive docs (paste token in Authorize):

https://mqtt.ishareradio.com/api/v1/subscriber/docs