RBAC Overview

RBAC Overview

Role-Based Access Control (RBAC) in Mantis provides granular security for all system resources.

Overview

Key Concepts

Users

Users are individual accounts that can authenticate to Mantis. Each user:

• Has an email and username unique within its tenant
• Can be assigned one or more roles
• May be scoped to a specific tenant
• Can authenticate via local credentials or external identity providers

Roles

Roles are named groups of permissions. Mantis includes system roles:

Role	Description
admin	Full system access with all permissions (protected)
operator	Deployment and target management (protected)
viewer	Read-only access to resources (protected)
tenant_admin	Full access within assigned tenant. Seeded but is_system = false, so it is not protected — holders of roles:update/roles:delete can modify or delete it.

Custom roles can be created to match your organizational needs.

Permissions

Permissions grant specific actions on resources. Format: resource:action

Component	Examples
Resource	deployments, targets, actions, users
Action	create, read, update, delete

Example permissions:

• deployments:create - Start new deployments
• targets:read - View target information
• users:delete - Remove user accounts

Permission Model

Permission Inheritance

Users receive permissions through their roles:

User → Roles → Permissions

If a user has multiple roles, they receive the union of all permissions:

Authorization Flow

Permission Checking

Every protected endpoint validates permissions:

// In handler
check_permission(&mut conn, audit, &auth.claims, "deployments:create").await?;

The check:

0. If the caller authenticated with an API key, the key’s own scopes must cover the permission first — a key whose owner has the permission still gets 403 (“API key lacks required scope”) if the key’s scopes are narrower.
1. Extracts user_id from JWT claims
2. Queries database for user’s permissions via roles
3. Returns success or logs denial to audit

System Roles

Admin

Full system access:

• All permissions across all resources
• Cannot be modified or deleted
• Typically assigned to platform administrators

Operator

Deployment operations:

• Create, read, update actions/sequences/solutions
• Create and manage deployments
• Register and manage targets

Viewer

Read-only access:

• View deployments and their status
• View targets and environments
• View actions, sequences, solutions
• Cannot make any modifications

Tenant Admin

Full access within tenant scope:

• tenant_admin holds every permission except these nine:
  • tenants:create - Cannot create new tenants
  • tenants:delete - Cannot delete tenants
  • system:admin - No system administration
  • settings:manage - Cannot modify system settings
  • audit:read - Cannot read audit logs
  • deployments:update - Cannot modify deployments
  • deployments:trigger - Cannot trigger deployments
  • deployments:override_freeze - Cannot override a deployment freeze
  • wireguard:manage - Cannot manage the WireGuard overlay
• The authoritative check is the roles_permissions join, not this list: every permission migration decides the tenant_admin grant explicitly, so the set moves. The seed excludes a different set from the one in force today — the schedules:* permissions it withholds were granted back later, and the four admin-only permissions above were added afterwards.
• Delegation is secure by default: when a tenant_admin (or any non-system-admin) assigns roles/permissions, it may confer only permissions it itself holds or ones carried by the baseline viewer/operator roles. Everything else — including any future system-tier permission — is refused. See Permissions → Tenant Admin Role for details.
• Ideal for delegated tenant management

Multi-Tenant Context

When a user has a tenant_id:

1. Handlers apply tenant scoping explicitly (via resolve_tenant_scope / effective_tenant_scope); several list endpoints resolve to own-tenant or global (tenant_id IS NULL), not own-tenant only
2. User can only access resources within their tenant
3. Cross-tenant access returns 404 (not 403) to prevent enumeration

Note

A tenant-less user sees resources across tenants only if it holds the admin role. admin is role membership, not a permission. A tenant-less user without that role is rejected outright with 403 (“User account is not associated with a tenant”), not given read-only global access.

Best Practices

Principle of Least Privilege

Assign the minimum permissions required:

Role Hierarchy Strategy

Create roles matching your organization:

Level	Example Roles	Typical Permissions
Platform	admin, auditor	Full access, read all
Operations	operator, deployer	Deployment management
Read-only	viewer, support	View resources
Custom	env-prod-admin	Specific environment access

Audit Compliance

Authorization denials are logged (successful checks are not):

{
  "event_type": "authz.permission_denied",
  "event_category": "authorization",
  "severity": "security",
  "actor_type": "user",
  "actor_id": "019b937d-4862-8e07-ac3a-1b8589d1b807",
  "actor_name": "alice",
  "action": "check_permission",
  "outcome": "denied",
  "outcome_reason": "Insufficient permission",
  "occurred_at": "2026-01-15T14:23:01"
}

Configuration

API Endpoints

Endpoint	Description
GET /api/v1/admin/users	List users
GET /api/v1/admin/roles	List roles
GET /api/v1/admin/permissions	List permissions
POST /api/v1/admin/roles/{id}/permissions	Assign permissions
POST /api/v1/admin/users/{id}/roles	Assign roles

Required Permission to Manage RBAC

Action	Permission
View users	users:read
Create users	users:create
Modify users	users:update
Delete users	users:delete
List/view roles	roles:manage
Create roles	roles:create
Modify roles	roles:update
Assign/remove permissions	roles:manage

Troubleshooting

User Cannot Access Resource

1. Check user’s assigned roles:

   curl -s -H "Authorization: Bearer $TOKEN" \
       https://api.mantis.local/api/v1/admin/users/$USER_ID/roles

2. Check role’s permissions:

   curl -s -H "Authorization: Bearer $TOKEN" \
       https://api.mantis.local/api/v1/admin/roles/$ROLE_ID/permissions

3. Verify required permission for endpoint

Permission Denied Despite Having Role

1. Verify the user-role assignment exists (users_roles has no active/expiry column — an assignment either exists or it does not)
2. Check if permission is assigned to the role
3. Review audit logs for specific denial reason

Next Steps

• Users - User management
• Roles - Role configuration
• Permissions - Permission reference
• Tenant Isolation - Multi-tenant access control