Skip to content

Roles & permissions

Vesana uses role-based access control (RBAC). Each role is a set of permissions — a permission is a single right, like hosts.create, alert_rules.edit, ai.query.

Deny-by-default: a new custom role starts with an empty permission list — nothing is allowed automatically. Every right must be granted explicitly. The super admin is the one exception: it bypasses the permission check entirely.

Roles apply instance-wide — the same role can be assigned to accounts in every tenant. Which tenant it applies in for whom is governed by tenant access and assignments.

Default roles

Four are shipped:

Role Who For what
Super Admin your setup team Full access to all tenants and all functions — including the ones without their own permission (managing users, teams, tenants and tenant groups, backup restore, preview features, instance-wide settings)
Admin tenant owner Everything in their tenants except: editing roles (users.edit_role), permanent purge (trash.purge), downloading backups (backup.export), the global visibility levels of trash/audit log/diagnostics log, and instance-wide icons/MIBs
Operator NOC, support team Read + handle alerts (ACK/close), create and edit downtimes, "Check now", defer updates, sites, edit dashboards/wiki/icons, use AI, the tenant's diagnostics log — no admin operations
Viewer end customer, stakeholder Read-only view, plus their own saved filters. No ACK, no downtimes, no "Check now" — anyone who needs that gets Operator or a custom role

Changes to the default roles

Since v1.9.350 acknowledging (alerts.acknowledge) and maintenance windows (downtimes.create/.edit) really require their permission — viewers could do both before despite lacking it. From v1.9.437 the same applies to "Check now" (check_results.reschedule), bulk-deleting checks (services.delete) and anomaly settings (hosts.edit); reading device and check data requires hosts.view / services.view (part of every default role). The built-in Admin role receives new permission areas automatically at startup; individually removed rights stay removed.

Admin, Operator and Viewer can be edited, Super Admin cannot. None of the four built-in roles can be deleted (marked "Built-in").

Custom roles

Admin → Users & access → Roles → New Role:

Field Meaning
Name freely chosen
Description optional
Permissions multi-select from the list, starting empty (deny-by-default). Create/edit/delete rights (*.create/.edit/.delete) need the matching *.view

Creating, changing or deleting roles requires users.edit_role in all tenants (because a role applies instance-wide) plus an identity confirmation. You cannot grant rights you don't hold in all tenants yourself. A role still used as someone's base role or in an assignment cannot be deleted.

Examples of sensible custom roles:

  • Auditor — only audit_log.view_tenant, nothing else
  • Read-only manager — all *.view permissions plus reports.view, dashboards.view
  • Push tester — only notifications.view + notifications.create, nothing else

Permission categories (selection)

Permissions follow the resource.action pattern. A selection of the most important categories:

Category Permissions Meaning
Hosts hosts.view / .create / .edit / .delete Creating/editing hosts
Services services.view / .create / .edit / .delete Host services (checks)
Dashboards dashboards.view / .create / .edit / .delete Dashboards + status pages (everyone sees the built-in overview)
Sites sites.view / .manage Sites (physical maps)
Alert rules alert_rules.view / .create / .edit / .delete Alert rules
Notifications notifications.view / .create / .edit / .delete Notification channels
Downtimes downtimes.view / .create / .edit / .delete Maintenance windows
Alerts alerts.view / .acknowledge / .close Handling ongoing problems
Check results check_results.view / .reschedule History + "Check now" / "Collect agent now"
Updates updates.defer / .decline / .install_now Defer automatic updates (Operator), decline or install immediately (Admin)
Saved filters saved_filters.view / .create / .edit / .delete Personal filters in lists
Tenant settings tenant_settings.view / .edit The tenant's alert grouping and notes
Credentials credentials.manage Create/change the tenant's credential sets (reading only needs hosts.view)
Collectors / agents collectors.*, agents.view / .manage Collection infrastructure
Profiles profiles.view / .create / .edit / .delete Device profiles
Monitoring scripts monitoring_scripts.view / .create / .edit / .delete Custom scripts
Reports reports.view / .export / .delete Reporting
Audit log audit_log.view (alias) / .view_own / .view_tenant / .view_global Who sees how much of the change history
System log system_log.view (alias) / .view_own / .view_tenant / .view_global Diagnostics-log visibility
Users users.view / .edit_role See the user and role list, or edit roles (needed in all tenants). Creating and changing users stays super-admin-only
Trash trash.view (alias) / .view_own / .view_tenant / .view_global / .restore / .purge Trash visibility + actions
Backup backup.export Downloading backups (restore stays hard super-admin-only)
Wiki wiki.view / .create / .edit / .delete Knowledge base
AI ai.query / .analyze AI features
Icons icons.view / .upload / .assign / … Icon management (*_global = instance-wide)
MIBs mibs.view / .upload / .delete / .upload_global MIB store; upload_global uploads instance-wide
Discovery discovery.manage_settings Auto-discovery platform defaults

The role editor itself shows you the full, current list when you create a custom role.

Fine-grained visibility levels (audit log, system log, trash)

These three areas each have three visibility levels instead of just yes/no:

  • .view_own — only your own actions/entries
  • .view_tenant — everything within your own tenant
  • .view_global — cross-tenant including instance-wide entries; only effective in an assignment scoped to "All tenants". From an assignment for individual tenants it counts like .view_tenant.

The old, coarser alias (e.g. trash.view) keeps working for existing custom roles and behaves like .view_own — for new roles, pick the appropriate level directly.

Feature visibility

Permissions don't just gate API access — they also drive UI visibility. Examples:

  • Without ai.query: the chat widget is hidden
  • Without alert_rules.view: the "Alert rules" menu item disappears
  • Without reports.view: the reports section disappears

Role assignment

The simple way: every user has a base role and tenant access (all or a selection) — both in the "Edit user" dialog. The role then applies in all of the user's tenants. That is enough for small setups.

Different access in different tenants (e.g. admin for customer A, read-only for customer B): via assignments. An assignment is role × scope; the scope is one tenant, a tenant group or "All tenants" (including future ones). You can assign

  • to a team — Admin → Users & access → Teams (super admins only). A team has a name, description, members and assignments; whoever joins the team gets its access immediately. This is the way for many users: create roles once, set up teams once, then just add people to teams.
  • to a single user — in the user list, row action Access & teams, section "Additional access for this account only".

Rules:

  • Access adds up. In each tenant, everything the base role, a team assignment or a direct assignment allows there applies. There is no "deny".
  • Actions without a tenant (e.g. creating a profile) are allowed by any assignment containing the permission.
  • Super admin is not an assignment but a property of the account — teams and assignments have no effect there.
  • Changes take effect immediately — signed-in users get the new access on their next click.
  • Visible but not allowed: someone who sees a tenant but lacks a permission there gets a clear "No permission … in this tenant" message.

Keeping track: "Access & teams" shows under Effective access, per tenant, which roles apply and where they come from (base role, direct, via team X, via group Y). With SSO or Active Directory, teams can be set from groups of the identity provider or directory — see SSO and Active Directory.

An assignment can select several tenants at once for the same role. If a team is deleted, its members lose the access they had only through that team. A role that is still used by an assignment cannot be deleted — Vesana names the number of assignments.

Audit trail

Permission changes appear in the audit log with a diff. "Who gave user X which permission?" — filter the audit log by the affected target.

Permission engineering — tips

  • Less is more — for each role, think about what's actually needed and leave the rest out
  • Separate *.view from *.create/*.edit/*.delete — many users only need to read
  • Be selective with AI permissions — enable ai.query for a handful of pilot users first, then expand
  • audit_log.view_tenant / system_log.view_tenant only for the audit function — a lot of detail, not interesting for everyone
  • Grant .view_global levels sparingly — they show cross-tenant and instance-wide entries

Next