# UNS permissions

> Limit a role to parts of the plant. Allow or deny a branch of the Unified Namespace, such as one site or one line, for everyone with that role.

Source: https://proxus.io/docs/administer/uns-permissions

At the end of this guide, users of a role see only the sites, areas and devices of the Unified Namespace (UNS) you
allowed, and across the platform only those devices, their alarms and their values. For example, the team in Lyon
sees `Meridian/Lyon_Foods_Plant` and everything under it, and nothing of Rotterdam.

## Before you start

- Sign in with a user that has the **Administrators** role.
- The role exists and is not administrative. See [Users and roles](https://proxus.io/docs/administer/users-and-roles).
- The devices have a place (enterprise, site, area...) so that they appear in the UNS. See
  [Unified Namespace](https://proxus.io/docs/concepts/unified-namespace).

## How the rules work

A UNS permission is a rule on a role: a **path** in the UNS and an **Access** of **Allow** or **Deny**.

- A path covers itself and everything under it. `Meridian/Lyon_Foods_Plant` covers every area, line and device of
  that site. There are no wildcards: MQTT signs such as `+` and `#` are removed when the rule is saved.
- Paths are compared segment by segment and are case-sensitive. `Meridian/Lyon` does not cover
  `Meridian/Lyon_Foods_Plant`.
- **Deny** wins over **Allow**. Allow a site and deny one line in it to hide only that line.
- A user with several roles gets what any of them allows: two site roles open both sites, and one role without
  UNS rules that reads devices opens every device.
- A role with no rule is not limited to a site: it sees every device it may read, but nothing in the UNS Explorer.
  A role with only **Deny** rules sees every device except the denied branches, and nothing in the UNS Explorer.
- Administrative roles always see everything; their rules are not used.

The rules decide which part of the plant a role works in; what it may do there (read, change) comes from its other
permissions. A device cannot be saved outside the role's paths, for example moved to another site.

## Allow a branch from the UNS Explorer

1. Go to **Organize > UNS Explorer**.
2. Right-click the node you want to give access to, for example the site `Lyon_Foods_Plant`.
3. Select **Allow Access to Role...**, or **Deny Access for Role...** to hide it.
4. In the dialog, select the role and then **Apply**.

*Screenshot: The UNS Explorer right-click menu on a site, with Allow Access to Role and Deny Access for Role marked*

1. **Allow Access to Role...** adds an allow rule for this node and everything under it.
2. **Deny Access for Role...** adds a deny rule.

These menu items are only shown to administrators.

*Screenshot: The Allow Access to Role dialog with the path Meridian/Lyon_Foods_Plant, the role list and the Apply button marked*

1. **Path** is the UNS path of the node you clicked.
2. The list shows every role that is not administrative.
3. **Apply** saves the rule. If the role already has a rule for this path, it is updated and turned on again.

## Add or change rules on the role

Go to **Security > Roles**, open the role and look at **UNS Topic Permissions** below the permission tabs.

- **New** adds a rule by hand: type the **ISA-95 Topic Prefix** (the path, such as
  `Meridian/Lyon_Foods_Plant/Packaging`) and choose the **Access**.
- **Paste UNS Path** adds an allow rule for a path you copied with **Copy Path** in the UNS Explorer right-click menu.
- Clear **Is Enabled** to switch a rule off without deleting it.

*Screenshot: A role limited to the Lyon site: the Site scope cell of the summary and the UNS rule Meridian/Lyon_Foods_Plant marked*

1. **Site scope** in the summary at the top of the role page: how many rules the role has and which paths they open
   and close, or **All sites** when it has none.
2. Each rule shows its path (**ISA-95 Topic Prefix**), its **Access** and whether it is enabled.

## Where the rules apply

| Place | Effect |
| --- | --- |
| **UNS Explorer** | Nodes outside the allowed paths are hidden. The parents of an allowed node stay visible so the user can open it. Device and data point counts count only what the user sees. |
| Devices: device list and page, Operations Center, plant map, Trend Workspace, Copilot | Only devices in the allowed paths are listed. A device page opened by its link is refused. |
| **Alerts** | Only the alarms of those devices. An alarm without a device belongs to no site and is hidden. |
| Device telemetry and trend notes | Only the rows of those devices. |
| AI agents through the [MCP server](https://proxus.io/docs/develop/mcp) | Devices and values outside the allowed paths are not returned. |
| **Dashboards** and **Reports** | Every query reads only the rows of those devices: telemetry, device metrics, devices, alarms and device statistics. Pipeline signal tables return no rows. A SQL query with its own `SETTINGS`, a table function (such as `remote` or `url`) or system tables is refused, and a query built by picking tables instead of SQL returns no rows (a report with one is refused). |
| **Scheduled deliveries** | A delivery runs with the site scope of the user who set it up (its owner): its recipients get what that user sees. |
| Free SQL: the MCP `telemetry_query` tool and the telemetry query of the REST API | Closed to a user whose roles are limited to a site, even with the **SQL queries** capability: a query cannot be limited to a site. |

Gateways, outbound targets, notification channels, rules, pipelines and functions do not carry a site; the role's
record permissions decide them.

> **Warning:**
UNS permissions do not limit the built-in MQTT broker. A client that connects to the broker with a valid token
reads topics regardless of these rules. Protect the broker with its own tokens. See [MQTT](https://proxus.io/docs/develop/mqtt).

## What's next

- [Users and roles](https://proxus.io/docs/administer/users-and-roles)
- [The UNS Explorer](https://proxus.io/docs/organize/uns-explorer)