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 (at the code level, not via a permission list).

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 (assigning roles, permanent purge, global view of trash/audit)
Admin tenant owner Everything within their own tenant except the hard super-admin-only rights (assigning roles, permanent purge, global trash/audit visibility)
Operator NOC, support team Read + handle alerts (ACK/close), create downtimes, "Check now", defer updates, edit dashboards/wiki/icons — 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.

You can edit these or create new roles. The four default roles shouldn't be deleted — they're the fallback for new users.

Custom roles

Admin → Access → Roles → New:

Field Meaning
Name freely chosen
Description optional
Permissions multi-select from the list, starting empty (deny-by-default)

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 Custom dashboards + status pages
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)
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 / .invite / .edit_role User management
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
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 (super-admin-only)

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

Each user has exactly one main role. Tenant access (which tenants a user sees at all) is managed separately — see Users & tenants.

Current limitation: only one role per user — no stacked roles. If a user needs several areas of responsibility, create a custom role covering the union of the needed permissions.

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
  • .view_global levels stay super-admin-only — they're cross-tenant and deliberately don't belong in standard custom roles

Next