Roles & RBAC

Built-in roles, custom role creation, granular permissions, and tenant-scoped role assignment.

Sophon's RBAC system lets you create roles with precisely the permissions your organization needs. Three roles ship out of the box; you can create any number of custom roles with arbitrary permission combinations.

Built-in roles

Role	What it grants
Admin	All permissions. User / role / tenant management, audit, license, compliance.
Operator	Operational permissions: approve tasks, restart services, manage Node devices, view system health. No user management.
Viewer	Read-only. Can view but not modify any resource.

These are fixed — you can't edit them (to protect against accidentally unlocking Admin). If you need a variant, create a custom role.

Permission catalog

Permissions are fine-grained and combine into roles. The full list:

Users & identity

ManageUsers — create / delete / suspend users
ManageRoles — create / edit custom roles
ManageTenants — create / manage tenants
AssignRoles — change a user's role
ViewUsers — see the user list

Resources

ManageAgents — create / edit / delete agents
ManageWorkflows — create / edit / delete workflows
ManageSkills — install / uninstall / configure skills
ManageMemory — write / delete memory entries (across users, if scoped)
ManageDocuments — upload / delete documents
ManageConnections — add / remove OAuth and API-key connections
ManageChannels — add / remove channel adapters
ManageCronJobs — create / edit / delete scheduled jobs
ManageWebhooks — create / edit / delete webhooks
ManageNodes — approve / configure / delete Sophon Nodes
ManageMcp — configure MCP client + server

Approvals & execution

ApproveActions — approve / reject high-risk actions
CancelTasks — cancel any running task (not just your own)
ViewActiveTasks — see the task ledger

Models & providers

ManageModels — add / remove LLM provider credentials
ViewBudgets — see budget utilization
ManageBudgets — set budget limits

System & operations

ManageSettings — edit Gateway configuration
ViewSystemHealth — Operations → System
RestartServices — pause / resume processing
ClearCaches — flush caches
GenerateOnboarding — create remote-access onboarding tickets

Audit & compliance

ViewAuditLogs — read the audit log
ExportAuditLogs — CSV / JSON export
ManageCompliance — generate compliance reports, configure retention

Licensing

ViewLicense — see license tier and features
ManageLicense — install / rotate license keys

Creating a custom role

Admin → Roles → New.

Name — e.g., finance-auditor, workflow-editor
Description — internal notes
Tenant scope (Enterprise) — all tenants / specific tenant
Permissions — check the boxes in the permission matrix

Save. The role appears in the user-edit dropdown.

Example: Workflow Editor

Permissions:
  ✓ ViewUsers              (needs to see who owns what)
  ✓ ManageWorkflows        (the point)
  ✓ ManageCronJobs         (workflows often trigger on cron)
  ✓ ManageWebhooks         (workflows accept webhooks)
  ✓ ApproveActions         (edit AI-authored workflows)
  ✓ ViewAuditLogs          (debug execution history)

Example: Compliance Auditor

Permissions:
  ✓ ViewUsers
  ✓ ViewAuditLogs
  ✓ ExportAuditLogs
  ✓ ManageCompliance
  ✓ ViewSystemHealth
  ✓ ViewLicense

Note the deliberate absence of ManageUsers — auditors observe but don't modify.

Tenant-scoped roles (Enterprise)

A role can be scoped to:

Global — applies in every tenant the user belongs to
Single tenant — applies only in the assigned tenant

In the user-edit screen, you assign a role per tenant. A user can be Admin in tenant A and Viewer in tenant B.

Single-tenant users (the common case) have one role assignment.

Assigning roles

From Dashboard

Admin → Users → <user> → Edit → Role.

From CLI

sophon admin users set-role <user-id> --role workflow-editor
sophon admin users set-role <user-id> --role admin --tenant acme

From SSO group mapping

If using SSO (SSO), you can map IdP groups to Sophon roles in the OIDC config:

{
  "Sophon": {
    "Auth": {
      "Sso": {
        "GroupClaim": "groups",
        "RoleMappings": {
          "sophon-admins": "Admin",
          "sophon-auditors": "compliance-auditor"
        }
      }
    }
  }
}

On SSO login, the user is auto-assigned the mapped role. Mappings are evaluated top-to-bottom; first match wins.

Permission enforcement

Every API endpoint is annotated with a required permission:

[RequiresPermission(Permission.ManageWorkflows)]
public static async Task<IResult> CreateWorkflow(...) { ... }

If the caller lacks the permission, the endpoint returns 403 Forbidden with a clear error message naming the missing permission.

Dashboard pages and CLI commands perform the same check client-side before showing a control — a user without ManageWorkflows doesn't see the New Workflow button.

Viewing effective permissions

Admin → Users → <user> → Effective Permissions shows the flat list of permissions this user has, deduplicated across tenant assignments. Useful for debugging "why can't they do X?" questions.

CLI equivalent:

sophon admin users effective-permissions <user-id>

Audit

Every role change, permission grant, and role creation/deletion is logged. Admin → Audit → category: rbac shows the RBAC trail with actor, subject, and diff.

Limits

Max custom roles: 100 per tenant (configurable).
Permission count: ~50 discrete permissions. Growing over time as new features land — existing custom roles aren't automatically granted new permissions (secure-by-default).
Role name uniqueness: within a tenant.

Where to go next

Users — creating users and assigning roles
SSO — group-to-role mapping
Audit Logging — tracking who has which permissions over time

On this page