---
name: zero-emqx
description: Provision a disposable MQTT namespace inside a shared EMQX 6 cluster. 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.
metadata:
  version: 0.1.0
---

# Zero EMQX

One HTTP call gets you one isolated MQTT namespace in a shared EMQX 6 cluster.
Topics are scoped per tenant via `namespace_as_mountpoint`, 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-manager.dev-ala.aws.mpaas.mqttce.net/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, Kubernetes label-value
rules. Stored on the per-tenant Secret; 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": "<43-char base64url 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 7 days (`TTL_SECONDS=604800` by default).
- 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, per-IP concurrent, or global cap exceeded. | Yes, after waiting |
| `500` | Manager misconfiguration or unexpected EMQX error. | Yes, check logs |
| `502` | EMQX returned 5xx. | Yes |
| `504` | Request deadline exceeded. | Yes, with backoff |

Error bodies are plain text.

## Health

- `GET /healthz` — liveness.
- `GET /readyz` — ready when EMQX and Kubernetes API are reachable.

## 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; EMQX prefixes the namespace internally. No client-side
configuration needed.