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 bit like host.create, alert_rule.edit, ai.query.

Default roles

Shipped:

Role Who For
super_admin your setup team sees all tenants, can do everything
tenant_admin customer owner sees own tenant only, can do everything in tenant
operator NOC, support team read + ack + downtime, no admin operations
viewer end customer, stakeholder read only

You can edit these or create new roles. Default roles shouldn't be deleted — they're fallbacks for new users.

Custom roles (Pro+)

/admin/roles → New:

Field Meaning
Name free
Description optional
Permissions multi-select from list
Tenant scope own tenant only / cross-tenant

Examples for sensible custom roles:

  • Auditor — audit.view, audit.export, nothing else
  • Read-only manager — all *.view permissions plus report.view, dashboard.view
  • Push tester — notification_channel.test, nothing else

Permission matrix (selection)

Permission Meaning
host.view / .create / .edit / .delete Hosts
host_service.view / .create / .edit / .delete / .ack Host services
profile.view / .create / .edit / .delete Profiles
tenant.view / .create / .edit / .delete / .cross_view Tenants
user.view / .create / .edit / .delete / .invite Users
role.view / .create / .edit / .delete Roles
alert_rule.view / .create / .edit / .delete / .test Alert rules
notification_channel.view / .create / .edit / .delete / .test Channels
dashboard.view / .create / .edit / .delete / .publish Dashboards
wiki.view / .create / .edit / .delete / .purge Wiki
script.view / .create / .edit / .delete Monitoring scripts
discovery.view / .scan / .import Discovery
audit.view / .export / .purge Audit log
trash.view / .restore / .purge Trash
report.view / .create / .schedule / .template_upload Reports
sla.view / .export SLA
downtime.view / .create / .edit / .delete Downtimes
ai.query / .analyze / .config AI features
status_page.view / .edit / .publish Status pages
system.health / .tune / .update System (super admin)
license.view / .activate License management
mobile_push.send_test / .manage_devices Push management

Full list: /admin/roles/permissions — code-generated from shared/permissions/registry.py.

Feature visibility

Permissions drive UI visibility, not just API access. Examples:

  • Without ai.query: chat widget invisible
  • Without alert_rule.view: menu item gone
  • Without report.view: reports section gone

Implementation: frontend/src/lib/permissions.ts with useHasPermission() hook. Combined with useAiVisible() etc. for compound cases.

Role assignment

One main role per user. Plus optional:

  • Tenant-specific roles for cross-tenant setups (super-admin acts as operator in tenant A, viewer in tenant B)

Current restriction: only one role per user — no stacked roles. Need multiple responsibilities? Custom role with the union.

Audit trail

Permission changes appear in audit log with diff. „Who gave user X the host.delete permission?" — filter target_kind = role.

Permission engineering — tips

  • Less is more — per role, only what's actually needed
  • Separate *.view from *.create — many users only need read
  • AI permissions selectively — enable ai.query for pilot users first, expand later
  • audit.view only for audit role — audit log has lots of detail, not for everyone

Next