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 built-in roles (Admin, Operator, Viewer) that cover common access patterns. For organizations that need more granular control, custom roles can be created with any combination of the 20+ available permissions. Built-in roles cannot be modified or deleted, ensuring there is always a known-good baseline for administrative access.

• 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 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 Built-in Roles

1. Navigate to Admin → Roles.
2. The role list displays all roles with their name, description, whether they are system-defined, and the number of assigned users.
3. Click any role to view its full permission list. Built-in roles (Admin, Operator, Viewer) are marked with a System badge and cannot be edited or deleted.

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 from the checklist. 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 Custom Role

1. Navigate to Admin → Roles and click the custom role you want to modify.
2. Update the name, description, or permissions.
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_system": 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_system": true,
      "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 Custom 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?

No. Built-in roles (Admin, Operator, Viewer) are system-defined and read-only. Attempting to update or delete a system role returns a 400 Bad Requesterror. This ensures a baseline access model always exists. Create custom roles for any variations you need.

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 a Built-in Role

• Built-in roles (Admin, Operator, Viewer) are marked as is_system: true and cannot be deleted or modified. The API returns 400 Bad Request.
• If you need a variation, create a custom role with the desired permissions instead.

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.