---
name: zero-emqx
description: Provision a disposable, isolated MQTT namespace. One unauthenticated POST returns MQTTS/WSS credentials valid for 7 days.
compatibility: Requires an MQTT client (mqttx, mosquitto, paho, mqtt.js, etc.) and outbound TLS to the deployment endpoint.
---

# Zero EMQX

One HTTP call gets you one isolated MQTT namespace. Topics are scoped per
tenant, so two tenants publishing to `temperature/sensor1` never see each
other's messages.

Tenants get one MQTT username (the instance ID) and one password. No
Dashboard, no admin REST API.

## Endpoint

```
POST https://zero.emqx.io/v1/instances
Content-Type: application/json
```

Unauthenticated. Rate limits are per source IP.

## Request

Body is optional:

```json
{ "tag": "my-app" }
```

`tag` (optional) — caller-supplied label, max 63 chars, restricted to a
DNS-friendly character set. Stored on the manager side; not visible to MQTT
clients.

A bare `POST` with no body is also valid.

## Response

`201 Created`:

```json
{
  "instance_id": "emqx-3a7f9c2b1d4e5678",
  "mqtts": {
    "host": "mqtt.example.com",
    "port": 8883,
    "uri": "mqtts://mqtt.example.com:8883"
  },
  "wss": {
    "host": "mqtt.example.com",
    "port": 8084,
    "uri": "wss://mqtt.example.com:8084/mqtt"
  },
  "credentials": {
    "username": "emqx-3a7f9c2b1d4e5678",
    "password": "<opaque random string>"
  },
  "expires_at": "2026-05-02T03:24:11Z"
}
```

The password is returned **exactly once**. Lose it and the tenant must request
a new instance.

## Lifecycle

- Each instance lives for a fixed TTL (currently 7 days).
- After expiry, the namespace, user, and active sessions are deleted.
- There is no `GET` or `DELETE` — instances live until TTL.

## Errors

| Status | Cause | Retry? |
|---|---|---|
| `400` | Invalid JSON or invalid `tag`. | No |
| `429` | Per-IP rate or per-IP concurrent limit exceeded. | Yes, after waiting |
| `500` | Manager misconfiguration or unexpected upstream error. | Yes, check logs |
| `502` | Upstream broker returned 5xx. | Yes |
| `503` | Service capacity reached. | Yes, with backoff |
| `504` | Request deadline exceeded. | Yes, with backoff |

Error bodies are JSON of the form `{"error":"<status text>","message":"<detail>"}`.

## Connecting

Use any MQTT client. Example with [mqttx CLI](https://mqttx.app/cli):

```bash
mqttx pub \
  -h "$MQTTS_HOST" -p 8883 -l mqtts \
  -u "$INSTANCE_ID" -P "$MQTT_PASSWORD" \
  -t "demo/topic" -m "hello"
```

Topics are bare names; the broker scopes them to your tenant internally. No
client-side configuration needed.