Accessing the IoT platform's API & MQTT broker

The IoT platform exposes two programmatic interfaces:

• a REST API (https://staging.yggio.net/api/…), fully documented in Swagger; and
• an MQTT broker (mqtt.staging.yggio.net:8883) for pub/sub - see the MQTT reference for full detail.

This page is a quick reference for accessing them with three common tools - curl, Postman and MQTT Explorer. For hands-on walkthroughs, see the training lessons: Curl, Postman, MQTT Explorer.

Authentication (REST)

Get a user access token and pass it as a Bearer header on every authenticated request.

POST https://staging.yggio.net/api/auth/local
Content-Type: application/json

{ "username": "…", "password": "…" }      →   { "token": "eyJ…" }

Authorization: Bearer <token>

Tokens expire; re-request as needed. For long-lived application access, create a client app (POST /api/client-apps) or, for MQTT, a Basic Credential Set (POST /api/basic-credentials-sets). The device data-push endpoint (/http-push/generic) instead authenticates with the device's own secret.

Common REST endpoints

Operation	Request
List devices	GET /api/iotnodes (filter: ?q=<field>)
One device	GET /api/iotnodes/{_id}
Update a device field	PUT /api/iotnodes/{_id}
Time series	GET /api/iotnodes/{_id}/stats?measurement=<field>&start=<ms>&distance=<s>
Push data to a generic device	POST /http-push/generic?identifier=secret (body includes secret)

See Swagger for the complete list and schemas.

curl

Command-line, ideal for scripting. Keep the token in a variable:

export YGGIO_URL="staging.yggio.net"
export YGGIO_TOKEN=$(curl -sS -X POST "https://$YGGIO_URL/api/auth/local" \
  -H "Content-Type: application/json" \
  -d '{"username":"USER","password":"PASS"}' | jq -r .token)

# read
curl -sS "https://$YGGIO_URL/api/iotnodes?q=temperature" \
  -H "Authorization: Bearer $YGGIO_TOKEN" | jq .

# push to a generic device (uses the device secret, not the token)
curl -sS "https://$YGGIO_URL/http-push/generic?identifier=secret" \
  -H "Content-Type: application/json" \
  -d '{"secret":"YOURDEVICESECRET","temperature":22}'

Postman

GUI HTTP client; good for exploring the API and running saved collections.

1. Create a POST {{baseUrl}}/api/auth/local request (JSON body with username/password); in the Tests tab save the token with pm.environment.set("token", pm.response.json().token).
2. On other requests, set header Authorization: Bearer {{token}}.
3. Read with GET {{baseUrl}}/api/iotnodes; push with POST {{baseUrl}}/http-push/generic?identifier=secret.
4. For bulk time-series import there is a ready-made collection - CSV import collection (see Lesson 1.4).

MQTT broker

Connect with any MQTT client:

Setting	Value
Host	mqtt.staging.yggio.net
Port	8883 (TLS - enable encryption + certificate validation)
Credentials	a Basic Credential Set
Publish in (generic device)	yggio/generic/v2/<id>
Subscribe to user output	yggio/output/v2/<userID>/#

Publishing to yggio/generic/v2/<id> auto-creates/updates a device; subtopics become nested objects. Full detail (channels, reserved topics, examples) is in the MQTT reference.

MQTT Explorer

MQTT Explorer is a desktop client for inspecting the broker:

1. New connection → Host mqtt.staging.yggio.net, Port 8883, Encryption on, Validate certificate on, and your Basic Credential Set.
2. Remove the default topics first. MQTT Explorer subscribes to # and $SYS/# by default, but the IoT platform does not grant access to the broker root - those subscriptions are refused (they need root privileges). Open Advanced, delete the # and $SYS/# entries, and add your own topic instead (e.g. your device or user-output topic). This is the most common thing people get wrong.
3. Publish a JSON payload to yggio/generic/v2/<id> to create/update a device.
4. Subscribe to your own topic to watch exactly what the IoT platform publishes, live.

Tool summary

Tool	Interface	Best for
curl	REST	quick tests, scripting/automation
Postman	REST	exploring the API, saved collections, CSV import
MQTT Explorer	MQTT	publishing test data, inspecting the broker
mosquitto_sub/pub	MQTT	CLI/scripted MQTT (see MQTT reference)

See also

• MQTT reference - broker in depth (channels, reserved topics, auth).
• Translator API - the translator object and data model.
• Swagger - the full REST API reference.
• Training: Curl, Postman, MQTT Explorer.