Skip to main content

MQTT Credentials

Retrieve MQTT broker connection information for all your devices or check platform quota limits.

Get MQTT Credentials​

Retrieve MQTT broker connection information for all your registered devices.

Endpoint​

GET /v1/iot/credentials

Request Example​

curl -X GET https://api.wayscloud.services/v1/iot/credentials \
  -H "Authorization: Bearer wayscloud_iot_prod_YOUR_API_KEY"

Response​

{
  "broker": "mqtt.wayscloud.services",
  "ports": {
    "mqtt": 1883,
    "mqtts": 8883,
    "ws": 8083,
    "wss": 8084
  },
  "protocols": ["mqtt", "mqtts", "ws", "wss"],
  "mqtt_versions": ["3.1.1", "5.0"],
  "devices": [
    {
      "device_id": "iot_dev_abc123",
      "name": "Temperature Sensor 01",
      "username": "iot_dev_abc123",
      "client_id": "iot_dev_abc123",
      "status": "active"
    },
    {
      "device_id": "iot_dev_xyz789",
      "name": "Smart Thermostat",
      "username": "iot_dev_xyz789",
      "client_id": "iot_dev_xyz789",
      "status": "active"
    }
  ]
}
info

Device passwords are not returned by this endpoint for security reasons. They are only shown once during device creation.

Connection Protocols​

WAYSCloud IoT Platform supports multiple MQTT connection protocols:

  • Port: 8883
  • Protocol: mqtts://
  • Encryption: TLS 1.2+
  • Best for: Production devices
import paho.mqtt.client as mqtt

client = mqtt.Client(client_id="iot_dev_abc123")
client.username_pw_set("iot_dev_abc123", "your_password")
client.tls_set()  # Enable TLS

client.connect("mqtt.wayscloud.services", 8883, 60)

MQTT (Plain)​

  • Port: 1883
  • Protocol: mqtt://
  • Encryption: None
  • Best for: Development and testing only
client = mqtt.Client(client_id="iot_dev_abc123")
client.username_pw_set("iot_dev_abc123", "your_password")

client.connect("mqtt.wayscloud.services", 1883, 60)
warning

Plain MQTT (port 1883) is not encrypted. Use only for testing. Always use MQTTS (port 8883) in production.

WebSocket over TLS (Secure)​

  • Port: 8084
  • Protocol: wss://
  • Encryption: TLS 1.2+
  • Best for: Browser-based applications, restricted networks
const mqtt = require('mqtt');

const client = mqtt.connect('wss://mqtt.wayscloud.services:8084/mqtt', {
  username: 'iot_dev_abc123',
  password: 'your_password',
  clientId: 'iot_dev_abc123',
  clean: true,
  keepalive: 60
});

client.on('connect', () => {
  console.log('Connected via WebSocket Secure');
});

Browser example:

<script src="https://unpkg.com/mqtt/dist/mqtt.min.js"></script>
<script>
  const client = mqtt.connect('wss://mqtt.wayscloud.services:8084/mqtt', {
    username: 'iot_dev_abc123',
    password: 'your_password',
    clientId: 'browser-client-' + Math.random().toString(16).substr(2, 8)
  });

  client.on('connect', () => {
    console.log('Connected from browser!');
    client.subscribe('devices/iot_dev_abc123/commands/#');
  });

  client.on('message', (topic, message) => {
    console.log('Received:', topic, message.toString());
  });
</script>

WebSocket (Plain)​

  • Port: 8083
  • Protocol: ws://
  • Encryption: None
  • Best for: Development and testing only
const client = mqtt.connect('ws://mqtt.wayscloud.services:8083/mqtt', {
  username: 'iot_dev_abc123',
  password: 'your_password',
  clientId: 'iot_dev_abc123'
});
warning

Plain WebSocket (port 8083) is not encrypted. Use only for testing. Always use WSS (port 8084) in production.

Get Platform Quota​

Check your IoT platform limits and current usage.

Endpoint​

GET /v1/iot/quota

Request Example​

curl -X GET https://api.wayscloud.services/v1/iot/quota \
  -H "Authorization: Bearer wayscloud_iot_prod_YOUR_API_KEY"

Response​

{
  "plan": "professional",
  "limits": {
    "max_devices": 1000,
    "max_messages_per_month": 10000000,
    "max_bandwidth_gb": 100,
    "max_message_size_kb": 1024,
    "messages_per_second_per_device": 100
  },
  "usage": {
    "current_devices": 42,
    "messages_this_month": 1523456,
    "bandwidth_used_gb": 12.5
  },
  "percentage_used": {
    "devices": 4.2,
    "messages": 15.2,
    "bandwidth": 12.5
  },
  "reset_date": "2025-12-01T00:00:00Z"
}

Python Example​

import requests

def check_quota():
    headers = {'Authorization': f'Bearer {API_KEY}'}

    response = requests.get(
        'https://api.wayscloud.services/v1/iot/quota',
        headers=headers
    )

    quota = response.json()

    print(f"Plan: {quota['plan']}")
    print(f"Devices: {quota['usage']['current_devices']}/{quota['limits']['max_devices']}")
    print(f"Messages: {quota['usage']['messages_this_month']:,}/{quota['limits']['max_messages_per_month']:,}")
    print(f"Bandwidth: {quota['usage']['bandwidth_used_gb']:.2f}/{quota['limits']['max_bandwidth_gb']} GB")

    if quota['percentage_used']['devices'] > 80:
        print("⚠️  Warning: Device limit almost reached!")

check_quota()

Connection Best Practices​

Keep-Alive Settings​

Configure appropriate keep-alive intervals to maintain connections:

# Recommended: 60-300 seconds
client.connect("mqtt.wayscloud.services", 8883, keepalive=60)

QoS Levels​

Choose the right Quality of Service level:

  • QoS 0 (At most once) - Fast, no acknowledgment
  • QoS 1 (At least once) - Acknowledged, may duplicate
  • QoS 2 (Exactly once) - Slowest, guaranteed delivery
# Publish with QoS 1 (recommended for telemetry)
client.publish("devices/iot_dev_abc123/telemetry", payload, qos=1)

# Subscribe with QoS 1
client.subscribe("devices/iot_dev_abc123/commands", qos=1)

Reconnection Strategy​

Implement exponential backoff for reconnections:

import time

def on_disconnect(client, userdata, rc):
    if rc != 0:
        print("Unexpected disconnect. Reconnecting...")
        retry_delay = 1

        while True:
            try:
                client.reconnect()
                break
            except:
                print(f"Reconnection failed. Retrying in {retry_delay}s...")
                time.sleep(retry_delay)
                retry_delay = min(retry_delay * 2, 60)  # Max 60s

client.on_disconnect = on_disconnect

Rate Limits​

MQTT Connections​

  • 100 messages/second per device
  • 1 MB maximum message size
  • 1000 concurrent connections per account (default)
  • 10 subscriptions per device (recommended)

HTTP API​

  • 1000 requests/minute per API key
  • Burst: Up to 200 additional requests

Troubleshooting​

Connection Refused​

Error: Connection refused (5)

Solutions:

  • Check username and password are correct
  • Verify device is in active status
  • Ensure API key is valid

Authentication Failed​

Error: Not authorized (5)

Solutions:

  • Regenerate device credentials
  • Check device hasn't been deleted
  • Verify correct client_id is used

Rate Limit Exceeded​

Error: Too many messages

Solutions:

  • Reduce message frequency
  • Batch multiple readings into one message
  • Upgrade your plan for higher limits

Next Steps​