Roles & Permissions

Overview

NetStacks uses role-based access control (RBAC) to govern what each user can do within the platform. Roles are named collections of permissions that are assigned to users. When a user attempts an action — whether through the web interface or the API — the Controller checks whether any of the user's assigned roles contain the required permission.

The system ships with three default roles (Admin, Operator, Viewer) that cover common access patterns. All roles are fully editable — admins can modify the permissions on any role, including the defaults, to match their organization's needs. The Admin role is protected from deletion to ensure there is always a known-good baseline for administrative access, but its permissions can still be customized. For organizations that need more granular control, additional custom roles can be created with any combination of the 20+ available permissions.

• Admin — Full access to all features, settings, user management, and audit logs.
• Operator — Manage devices, credentials, templates, stacks, and tasks. No access to admin settings or user management.
• Viewer — Read-only access to devices, credentials (without password visibility), sessions, and knowledge base.

How It Works

Permission Model

Permissions follow a resource.action naming convention. The wildcard pattern resource.* grants full control over a resource category. Each API endpoint and UI action is guarded by a specific permission check implemented as an Axum request extractor that loads the user's permissions from PostgreSQL before every protected request.

Complete Permission Reference

The following table lists every permission available in NetStacks Controller. Permissions are stored as JSON arrays on each role and checked at the API layer.

Built-in Role Permissions Matrix

The following matrix shows which permissions each built-in role includes:

Permission Grid UI

The role editor uses a collapsible category grid for managing permissions visually. Permissions are organized into four categories:

• Devices & Network — device inventory, credentials, SNMP, SSH CA
• Sessions & Connectivity — terminal sessions, session recordings
• AI & Automation — AI chat, agents, tasks, knowledge base, MOPs
• Administration — users, roles, settings, audit logs

Each category header has a checkbox that toggles all permissions within that group. An All Permissions master toggle at the top maps to the * wildcard, granting every permission in the system. Expanding a category reveals individual permission toggles for fine-grained control.

Terminal Enforcement

Permissions are enforced in the terminal UI, not just at the API layer. When a user logs in, the terminal reads their permissions from the /api/capabilities endpoint. Sidebar tabs are hidden for users who lack the required permission — for example, a user without sessions.connect will not see the Sessions tab at all. Within visible features, action buttons that require additional permissions are disabled and display a tooltip explaining which permission is needed.

Permission Inheritance

Wildcard permissions (e.g., credentials.*) include all specific permissions within that category. A user with credentials.* automatically has credentials.view, credentials.use, andcredentials.view_password. The permission checker evaluates this at runtime by matching the required permission key against the user's permission list with wildcard expansion.

Step-by-Step Guide

Viewing Roles

1. Navigate to Admin → Roles.
2. The role list displays all roles with their name, description, and the number of assigned users.
3. Click any role to view and edit its permissions using the category grid. All roles — including the default Admin, Operator, and Viewer roles — can have their permissions modified.

Creating a Custom Role

1. Navigate to Admin → Roles.
2. Click New Role.
3. Enter a name (e.g., Network Operator) and optional description (e.g., Device and template management for the NOC team).
4. Select permissions using the category grid. Expand each category to toggle individual permissions, or use the category checkbox to grant all permissions in a group. For a typical network operator, you might select: devices.*, credentials.view, credentials.use, sessions.*, tasks.*, and mops.view.
5. Click Create. The role is immediately available for assignment to users.

Updating a Role

1. Navigate to Admin → Roles and click the role you want to modify.
2. Update the name, description, or permissions using the category grid.
3. Click Save. Changes take effect immediately for all users with this role on their next API request (permissions are loaded per-request, not cached).

Assigning Roles to Users

1. Navigate to Admin → Users and open a user's profile.
2. In the Roles section, add or remove roles as needed.
3. Click Save. The user's effective permissions update immediately.

Code Examples

Role management endpoints are under /api/admin/roles. Read operations require roles.view; write operations require roles.*.

List All Roles

curl https://netstacks.dc1.example.net/api/admin/roles \
  -H "Authorization: Bearer $TOKEN"

Response:

{
  "roles": [
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
      "name": "Admin",
      "description": "Full system access",
      "permissions": [
        "users.view", "users.*", "roles.view", "roles.*",
        "credentials.view", "credentials.use", "credentials.view_password", "credentials.*",
        "devices.*", "sessions.view", "sessions.*", "tasks.*",
        "ai.chat", "knowledge.view", "knowledge.*", "agents.*",
        "mops.view", "mops.*", "ssh_ca.*",
        "admin.settings", "admin.audit"
      ],
      "is_protected": true,
      "created_at": "2025-01-01T00:00:00Z"
    },
    {
      "id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
      "name": "Operator",
      "description": "Manage devices, run tasks, view configs",
      "permissions": [
        "credentials.view", "credentials.use", "credentials.*",
        "devices.*", "sessions.view", "sessions.*", "tasks.*",
        "ai.chat", "knowledge.view", "mops.view", "mops.*"
      ],
      "is_protected": false,
      "created_at": "2025-01-01T00:00:00Z"
    }
  ]
}

Create a Custom Role

curl -X POST https://netstacks.dc1.example.net/api/admin/roles \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Network Operator",
    "description": "Device and template management for NOC team",
    "permissions": [
      "devices.*",
      "credentials.view",
      "credentials.use",
      "sessions.view",
      "sessions.*",
      "tasks.*",
      "mops.view"
    ]
  }'

Update a Role

curl -X PUT https://netstacks.dc1.example.net/api/admin/roles/d4e5f6a7-b8c9-0123-def0-456789012345 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "permissions": [
      "devices.*",
      "credentials.view",
      "credentials.use",
      "sessions.view",
      "sessions.*",
      "tasks.*",
      "mops.view",
      "ai.chat"
    ]
  }'

Delete a Custom Role

curl -X DELETE https://netstacks.dc1.example.net/api/admin/roles/d4e5f6a7-b8c9-0123-def0-456789012345 \
  -H "Authorization: Bearer $TOKEN"

Questions & Answers

What permissions does the default Admin role have?

The Admin role has every permission in the system, including users.*,roles.*, credentials.*, devices.*,sessions.*, tasks.*, ai.chat,knowledge.*, agents.*, mops.*,ssh_ca.*, admin.settings, and admin.audit. This is the only built-in role with access to user management, role management, system settings, and audit logs.

Can I create custom roles?

Yes. Navigate to Admin → Roles and click New Role. Select any combination of the 20+ available permissions to match your team's access requirements. Common custom roles include “NOC Operator” (device and session access without credential password visibility) and “Security Auditor” (read-only access plus audit log viewing).

How do I see what permissions a user has?

Open the user's profile in Admin → Users. The assigned roles are listed with their permissions. Since the effective permission set is the union of all role permissions, review each assigned role to understand the complete access picture. Via the API, GET /api/admin/users/:id returns the user with their roles and permission lists.

Can a user have multiple roles?

Yes. A user can have any number of roles assigned. The effective permissions are the union of all permissions across all roles — permissions are never subtracted. For example, assigning both “Viewer” and a custom “Device Operator” role gives the user all permissions from both.

What happens if I remove a permission from a role that users depend on?

The change takes effect immediately. All users assigned that role lose access to features protected by the removed permission on their next API request. Permissions are checked at request time (not cached in tokens), so there is no delay. Review the role's user count before removing permissions to understand the impact.

Can I modify or delete built-in roles?

Yes, all roles are fully editable. You can modify the permissions on the default Admin, Operator, and Viewer roles to match your organization's needs. The only restriction is that the Admin role cannot be deleted — this ensures there is always at least one administrative role in the system. Operator, Viewer, and any custom roles can be deleted freely.

How are permissions enforced in the terminal?

When a user logs in, the terminal reads their permissions from the /api/capabilities endpoint. Sidebar tabs for features the user cannot access are hidden entirely. Within visible features, buttons that require additional permissions are disabled and show a tooltip indicating the missing permission. This enforcement happens client-side based on the capabilities response.

Troubleshooting

User Cannot Access a Feature

• Check which roles the user has in Admin → Users.
• Verify that at least one assigned role includes the required permission. For example, deploying stacks requires tasks.* or devices.* depending on the operation.
• Remember that wildcard permissions (e.g., credentials.*) include all sub-permissions. A user with credentials.* does not also need credentials.view explicitly.

Permission Denied on API Call (403 Forbidden)

• The API response includes {"error": "Insufficient permissions"}. This means the user's token is valid but lacks the required permission.
• Check the API documentation or endpoint's #[utoipa::path] annotation to see which permission is required (e.g., ManageUsers maps to users.*).
• Verify the user's token is fresh. Permissions are loaded from the database on every request, so recent role changes take effect immediately.

Cannot Delete the Admin Role

• The Admin role is protected from deletion to ensure there is always at least one administrative role. The API returns 400 Bad Request if you attempt to delete it.
• You can still modify the Admin role's permissions — only deletion is restricted. All other roles (including Operator and Viewer) can be both modified and deleted.

Role Name Already Exists

• Role names must be unique within an organization. The API returns 400 Bad Request if you try to create or rename a role to an existing name.
• Check Admin → Roles for existing roles with similar names.

Related Features

• User Management — Create users and assign roles to control their access.
• Audit Logs — Track role changes including creation, updates, deletions, and user assignments.
• API Authentication — Understand how permissions are enforced on every API request through JWT tokens.
• Credential Folders — Organize credentials with folder-level access control that works alongside RBAC.
• Credential Vault — Manage the encrypted vault where credentials are stored with role-based access.