Permissions & Scopesv7.0.20
Two access-control vocabularies govern the Netmon API — permissions and scopes — and they do not map one to one. This reference lists both, crosswalks them, and documents the eight canonical OAuth scopes in full.
Two access-control vocabularies govern the API, and they do not map one to one. This page brings both together: first the permission catalogue that gates every REST call, then the permission-to-scope crosswalk, and finally the OAuth scope set that gates the MCP tool surface used by AI clients — the eight canonical scopes in full, how a token carries them, and where the appliance publishes them for discovery.
Permissions
A permission is a capability granted to a user. The REST API enforces permissions on every call — the gate shown on each endpoint entry. A user may hold any combination; the super-administrator permission (sa) bypasses all checks.
| Permission | Governs |
|---|---|
sa | Everything. Bypasses all permission and tag-scope checks. The super-administrator. |
overwatch | The fleet-wide Overwatch read surface. |
devices | Reading the device inventory and per-device data. |
write_devices | Adding, importing, editing, and deleting devices, and configuring their trackers (interfaces, disks, services, ports, OIDs, latency) and credentials. |
vne | The Visual Network Explorer / NetFlow surface. |
logs | Syslog, Windows event-log, and IDS-event reads and log filters. |
alerts | All alerting: definitions, routing rules, outlets, templates, and history. |
reports | The report queries. |
urls | URL trackers. |
tools | The network tools (ping, MTR, traceroute, SNMP walk, port scan, speed test, iPerf). |
capture | Packet capture. |
system | Appliance settings, backups, retention, partitions, downloadables, and OAuth client approval. |
users | User administration, MFA management, and on-behalf token administration. |
agentadmin | Privileged Windows-agent control and enrollment-token issuance. |
api | The prerequisite for using the API programmatically at all — minting personal access tokens and completing any OAuth flow. |
Scopes (crosswalk)
A scope is carried by an OAuth or MCP token and names a functional area. Scopes gate the Model Context Protocol tool surface used by AI clients; they are chosen at consent time. A direct REST call is gated by the user’s permissions, not by the token’s scopes — so the crosswalk below is a guide to which functional area a scope corresponds to, not a per-endpoint enforcement table.
| Scope | Functional area | Closest permission(s) |
|---|---|---|
mcp:devices | Devices and device data (incl. interface trackers and throughput) | devices, write_devices, overwatch |
mcp:alerts | Alerting | alerts |
mcp:logs | Logs and events | logs |
mcp:reports | Reports | reports |
mcp:vne | NetFlow / Visual Network Explorer | vne |
mcp:tools | Network tools | tools |
mcp:capture | Packet capture | capture |
mcp:system | Settings and administration | system, users, agentadmin |
Every scope maps to a permission domain, but the mapping is not one-to-one in both directions. One scope can span several permissions — mcp:devices covers devices/write_devices/overwatch (interface trackers ride write_devices), and mcp:system covers system/users/agentadmin. And a few permissions have no dedicated scope: urls (URL trackers are reached with the same token as the rest of the API), plus the meta/admin permissions api, sa, users, and agentadmin. Treat scopes as coarse functional-area labels for tokens and permissions as the authoritative per-call gate.
The eight OAuth scopes
When an OAuth or MCP client signs in, it requests a set of scopes and the user approves them at consent time. The appliance recognizes exactly eight scopes; a consent request for any name outside this set is refused rather than silently trimmed. The eight, in canonical order:
| Scope | Grants the token access to |
|---|---|
mcp:devices | The device inventory and per-device data (including interface trackers and throughput). |
mcp:alerts | Alert definitions, routing, outlets, and history. |
mcp:logs | Syslog, Windows event logs, and IDS events. |
mcp:reports | The report queries. |
mcp:system | Appliance settings and administrative data. |
mcp:tools | The network tools (ping, traceroute, MTR, SNMP walk, and so on). |
mcp:vne | NetFlow and the Visual Network Explorer. |
mcp:capture | Packet capture. |
How scopes are used
- A personal access token is scoped at creation. By default it receives all eight scopes (the same breadth the web interface holds); narrow it at mint time to limit what an MCP client may do with it. See Authentication & OAuth.
- An OAuth token is scoped at consent. The client names the scopes it wants in the authorization or device-code request, and the user sees and approves exactly that list. Requesting a scope outside the eight fails the request with
400, so a client cannot phish consent for a fabricated capability. - Scopes gate the MCP tool surface that AI assistants drive. A direct REST call authenticated with a bearer token is gated by the calling user’s permissions (see Permissions above), independent of the token’s scopes.
Discovery
The canonical scope list is published in the appliance’s OAuth discovery documents, so a conformant client can read it rather than hard-coding it:
curl https://APPLIANCE/.well-known/oauth-authorization-serverThe scopes_supported field of that document is the same eight scopes listed above. See Authentication & OAuth for the full discovery-document shape and the OAuth flows that consume it.