---
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 -> Security -> *Create Account* -> *Add Permissions*

Creates an MQTT account on the LitmusUNS 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.

### 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/realms/standalone/protocol/openid-connect/token` (see top-level Litmus UNS section auth).

### Step table

| Step | Name in Collection | GraphQL operation | Input | Output / What to capture |
|------|-------------------|-------------------|-------|--------------------------|
| 1 *(optional)* | Get Accounts | `query Account { account { ... } }` | -- | Existing accounts -- avoid name collision |
| 2 | Create Account | mutation `createAccount` | `{ username, password, acType: "General", enabled: false }` | Account `id` (UUID) |
| 3 | Add Account Rules | mutation `addAccountRules` | `{ accountId: <from step 2>, rules: [{ path: "<topic_path>", perm: "Sub" \| "Pub" \| "PubSub" }] }` | Rules attached |
| 4 | Enable Account | mutation `enableAccount` | `{ accountId: <from step 2> }` | Account active |
| 5 *(verify)* | Account Details | `query account(id: ...)` | Account `id` | Final state with rules + connected clients |

### Variants

- **For binding a Litmus Edge to UNS**: replace step 2 with `Create LitmusEdge Activation Token` (mutation that returns a token the LE uses during enrollment). Steps 3-5 then operate on the auto-created account once the LE connects.
- **Cleanup**: `Disable Account`, `Remove Account Rules`, `Remove Account`, or `Reset Account Password` all share the same endpoint with their respective mutations.

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