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.