---
parent: /workflows/agents.md
back_out_url: /workflows/agents.md
---

# Workflow 15: Provision a UNS MQTT Account

> You are at https://api.litmus.io/workflows/provision-mqtt-account.md
> Parent: https://api.litmus.io/workflows/agents.md
> If this is the wrong workflow, back out to the index above.

## 15. Provision a UNS MQTT Account

**UI trigger**: LUNS -> MQTT -> Accounts -> *Create Account* -> *Add Rules*

Creates an MQTT account on the Litmus Unify broker, sets its ACL rules (which topic paths it can subscribe/publish to), and enables it. All LUNS calls are GraphQL POSTs to a single endpoint -- the operation is selected by the GraphQL query/mutation, not by URL.

> **Applies to:** Litmus Unify **2.0.x**. In **<v2.0.0** these account operations live in a separate "Security" folder, `Create Account` accepted a supplied password (2.0.x generates one), there is no dedicated `accountDelete` (removal went through `accountRemoveRules`), and the activation token is named "Create LitmusEdge Activation Token". See /luns/mqtt.md for the per-operation version map.

### URL pattern

Every step is `POST {{uns_url}}/mqtt/gql` with header `Authorization: Bearer <UNS_TOKEN>`. The token is obtained once per session via the LUNS OAuth2 password grant at `{{uns_url}}/auth/v3/oauth/token` (see the top-level Litmus Unify section auth: /luns/agents.md#authentication).

### Step table

| Step | Name in Collection | GraphQL operation | Input | Output / What to capture |
|------|-------------------|-------------------|-------|--------------------------|
| 1 *(optional)* | List Accounts | `query ListAccounts` | -- | Existing accounts -- avoid username collision |
| 2 | Account Create | mutation `accountCreate` | `{ username: "<name>", acType: "General" }` | Account `id` (UUID) **and** the generated `password` -- shown once, capture it now |
| 3 | Account Add Rules | mutation `accountAddRules` | `{ acctId: <from step 2>, rules: [{ path: "<topic_path>", perm: "Sub" \| "Pub" \| "PubSub" \| "Deny" }] }` | Rules attached |
| 4 | Account Enable | mutation `accountEnable` | `{ acctId: <from step 2> }` | Account active |
| 5 *(verify)* | Account | `query Account(id: <UUID>)` | Account `id` | Final state with rules + connected clients |

`acType` is `General` (default) or `Litmus`. `path` accepts MQTT topic filters, e.g. `enterprise/site/area/+/temperature`.

### Variants

- **For binding a Litmus Edge to Unify**: use `Create Token` (mutation `createToken` with `{ publicURL: "<callback_url>", accountId?: <UUID>, mqttPort?: <int> }`). It returns a one-time `token` blob the LE consumes during enrollment; bind it to a specific account via `accountId`, or omit to auto-create one on connect.
- **Cleanup / edits**: `Account Disable` (`accountDisable`), `Account Remove Rules` (`accountRemoveRules`), `Account Update Rules` (`accountUpdateRules`), `Account Update` (`accountUpdate`), and `Account Delete` (`accountDelete`) all share the same endpoint with their respective mutations. Each account mutation takes `acctId`.

> **All LUNS endpoints** in this collection (Dashboard, UNS, MQTT, Integrations, Configuration) -- 46 in total -- target the same `/mqtt/gql` URL. Folder structure is purely organizational. The operation is in the GraphQL body.