Roles

Roles

Configure and manage roles for fine-grained access control in Mantis.

Overview

Role Model

Field	Type	Description
id	UUID	Unique identifier
name	String	Role name (unique; lowercase is convention, not enforced)
description	String	Human-readable description
is_system	Boolean	Protected: cannot be modified, re-permissioned, or deleted
created_at	DateTime	Creation timestamp
updated_at	DateTime	Last modification

System Roles

System roles are created during installation and cannot be deleted.

Admin

Full system administrator access:

Permissions: ALL (115 permissions)
is_system: true

Capabilities:

• All CRUD operations on all resources
• System configuration and settings
• User and role management
• Tenant administration
• Encryption key management

Operator

Day-to-day deployment operations:

Permissions: 30+ deployment/operational permissions
is_system: true

Capabilities:

• Create, read, update actions/sequences/solutions
• Create and manage deployments
• Register and manage targets
• View and update environments
• Read system statistics
• Create promotions and rollbacks

Cannot:

• Manage users or roles
• Modify system settings
• Delete resources (most types)
• Create/manage tenants

Viewer

Read-only access to operational resources:

Permissions: 20 read permissions
is_system: true

Capabilities:

• View all deployment-related resources
• View targets and environments
• View deployment history and status
• View system statistics

Cannot:

• Create, modify, or delete any resources
• Execute deployments
• View admin settings

Tenant Admin

Full access within tenant scope:

Permissions: All except system-level
is_system: false (NOT protected -- see caution below)

tenant_admin is not a protected role

Unlike admin, operator and viewer (is_system = true), tenant_admin is seeded with is_system = false. The update/delete/re-permission guards key off that flag, so anyone holding roles:update or roles:delete can re-permission or delete tenant_admin outright. Treat those permissions accordingly.

Capabilities:

• All operations within assigned tenant
• Manage tenant-scoped users
• Configure tenant settings
• Full deployment lifecycle management

Cannot — twenty-one permissions are withheld, each reaching outside a single tenant:

Withheld	Reaches
tenants:create, tenants:delete	The tenant list itself
system:admin, settings:manage	Platform administration and global settings
audit:read	Every tenant’s audit trail
deployments:update, deployments:trigger, deployments:override_freeze, deployments:execute_off_target	Deployment state, freeze windows, and off-target execution
wireguard:manage	The shared overlay network
encryption:stats, encryption:verify	Platform encryption status, which has no tenant dimension
roles:create, roles:delete	Roles, a global namespace shared by every tenant
registrations:create	Pre-registration, which writes a record with tenant_id NULL
execution_pools:read, execution_pools:create, execution_pools:update, execution_pools:delete	Execution pools, which carry no tenant_id
mailer:read, mailer:manage	The shared platform mailer

roles:update and roles:manage are held, not withheld: those paths scope the target user and are ceilinged by assert_caller_holds_permission, so a tenant_admin can re-permission its own users but cannot mint a role carrying anything it does not already hold.

schedules:* and notifications:* are held in full.

Separately, when a tenant_admin delegates roles/permissions to others, a secure-by-default ceiling applies: it may confer only permissions it itself holds or ones carried by the baseline viewer/operator roles — anything else, including any future system-tier permission, is refused (mandible/src/routes/admin/users.rs, roles.rs). See Permissions → Tenant Admin Role.

API Operations

Note

Listing roles (GET /api/v1/admin/roles) and viewing a role (GET /api/v1/admin/roles/{id}) require the roles:manage permission. The roles:read permission only gates the role-users sub-endpoint (GET /api/v1/admin/roles/{id}/users).

List Roles

curl -X GET \
    -H "Authorization: Bearer $TOKEN" \
    "https://api.mantis.local/api/v1/admin/roles?page=1&limit=20"

Response:

{
  "data": [
    {
      "id": "019b937d-4862-802a-9dd6-b840c22b87ac",
      "name": "admin",
      "description": "Full system administrator with all permissions",
      "is_system": true,
      "user_count": 2,
      "permission_count": 115,
      "created_at": "2024-01-01T00:00:00Z"
    },
    {
      "id": "019b937d-4862-8e07-ac3a-1b8589d1b807",
      "name": "operator",
      "description": "Can manage deployments and targets",
      "is_system": true,
      "user_count": 10,
      "permission_count": 54,
      "created_at": "2024-01-01T00:00:00Z"
    }
  ],
  "meta": {
    "total": 5,
    "page": 1,
    "limit": 20,
    "total_pages": 1,
    "has_next": false,
    "has_prev": false
  }
}

Get Role Details

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

Response:

{
  "id": "019b937d-4862-8e07-ac3a-1b8589d1b807",
  "name": "operator",
  "description": "Can manage deployments and targets",
  "is_system": true,
  "permission_groups": [
    {
      "resource": "actions",
      "permissions": [
        {
          "id": "019b937d-4862-8ba3-98ce-0f03fba1c12d",
          "name": "actions:create",
          "resource": "actions",
          "action": "create",
          "description": "Create new actions"
        },
        {
          "id": "019b937d-4862-892f-8964-135631fe2351",
          "name": "actions:read",
          "resource": "actions",
          "action": "read",
          "description": "View actions"
        }
      ]
    },
    {
      "resource": "deployments",
      "permissions": [
        {
          "id": "019b937d-4862-8e2a-88e4-d34627a858db",
          "name": "deployments:create",
          "resource": "deployments",
          "action": "create",
          "description": "Start new deployments"
        }
      ]
    }
  ],
  "users": [
    {
      "id": "019b937d-4862-8e07-ac3a-1b8589d1b807",
      "username": "bob",
      "email": "bob@example.com",
      "display_name": "Bob Jones"
    }
  ],
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": null
}

Create Role

curl -X POST \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
        "name": "deployer",
        "description": "Can only create and monitor deployments",
        "permission_ids": [
            "019b937d-4862-8ba3-98ce-0f03fba1c12d",
            "019b937d-4862-892f-8964-135631fe2351",
            "019b937d-4862-8e2a-88e4-d34627a858db"
        ]
    }' \
    "https://api.mantis.local/api/v1/admin/roles"

Update Role

curl -X PUT \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
        "name": "deployer-updated",
        "description": "Updated description"
    }' \
    "https://api.mantis.local/api/v1/admin/roles/$ROLE_ID"

Caution

System roles (is_system: true) cannot be modified.

Delete Role

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

Caution

System roles cannot be deleted. Deleting a role removes it from all assigned users.

Permission Management

List Role Permissions

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

Assign Permissions

curl -X POST \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
        "permission_ids": [
            "019b937d-4862-8ba3-98ce-0f03fba1c12d",
            "019b937d-4862-892f-8964-135631fe2351",
            "019b937d-4862-8e2a-88e4-d34627a858db"
        ]
    }' \
    "https://api.mantis.local/api/v1/admin/roles/$ROLE_ID/permissions"

Remove Permissions

curl -X POST \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
        "permission_ids": ["019b937d-4862-8ba3-98ce-0f03fba1c12d"]
    }' \
    "https://api.mantis.local/api/v1/admin/roles/$ROLE_ID/permissions/remove"

List Role Users

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

Custom Role Examples

Note

The blocks below list permission sets conceptually. The API’s CreateRoleRequest takes permission_ids (UUIDs), not permission names, and rejects unknown fields — resolve each name to its permission id (via GET /api/v1/admin/permissions) before POSTing.

Deployment-Only Role

For users who can only run deployments:

{
  "name": "deployment-executor",
  "description": "Can create and monitor deployments only",
  "permissions": [
    "deployments:create",
    "deployments:read",
    "deployments:cancel",
    "targets:read",
    "solutions:read",
    "environments:read"
  ]
}

Environment-Specific Admin

For managing a specific environment:

{
  "name": "prod-admin",
  "description": "Production environment administrator",
  "permissions": [
    "deployments:create",
    "deployments:read",
    "deployments:cancel",
    "targets:read",
    "targets:update",
    "environments:read",
    "environments:update",
    "freezes:create",
    "freezes:read",
    "freezes:update",
    "promotions:create",
    "rollbacks:create"
  ]
}

Read-Only Auditor

For compliance and audit access:

{
  "name": "auditor",
  "description": "Read-only access for audit purposes",
  "permissions": [
    "actions:read",
    "sequences:read",
    "solutions:read",
    "targets:read",
    "deployments:read",
    "environments:read",
    "users:read",
    "roles:read",
    "freezes:read",
    "promotions:read",
    "rollbacks:read",
    "statistics:read"
  ]
}

Target Manager

For infrastructure team managing targets:

{
  "name": "target-manager",
  "description": "Manage targets and registrations",
  "permissions": [
    "targets:create",
    "targets:read",
    "targets:update",
    "targets:delete",
    "registrations:read",
    "registrations:approve",
    "registrations:reject",
    "registrations:revoke",
    "registration_tokens:create",
    "registration_tokens:read",
    "registration_tokens:revoke",
    "certificates:read",
    "environments:read",
    "environments:manage_targets",
    "tags:read"
  ]
}

Role Hierarchy Patterns

Note

Mantis has no role inheritance mechanism — the “patterns” below are naming and design conventions, implemented by duplicating permission sets. viewer and operator already exist as protected system roles; do not try to recreate them.

Inheritance Pattern (convention)

Model roles that build on each other by copying the lower role’s permissions:

Implementation:

1. Create base viewer with read permissions
2. Create operator with viewer permissions + write permissions
3. admin has all permissions (system role)

Separation Pattern

Create distinct roles for different functions:

Composite Pattern

Assign multiple roles to users:

Audit Trail

All role operations are logged:

Event	Category	Severity
authz.role_created	Authorization	Info
authz.role_updated	Authorization	Info
authz.role_deleted	Authorization	Info
authz.role_permissions_assigned	Authorization	Security
authz.role_permissions_removed	Authorization	Security

Best Practices

Role Naming

• Use lowercase with hyphens: prod-admin, target-manager
• Be descriptive: deployment-executor not de
• Include scope if applicable: env-staging-deployer

Permission Assignment

1. Start minimal - Add permissions as needed
2. Group logically - Keep related permissions together
3. Document purpose - Clear descriptions help maintenance
4. Regular review - Audit permissions quarterly

Role Assignment Strategy

Avoiding Common Mistakes

Mistake	Impact	Solution
Too many admins	Security risk	Limit to 2-3 admins
Overly broad roles	Excess access	Create specific roles
Orphaned roles	Maintenance burden	Regular cleanup
No role descriptions	Confusion	Document purpose

Database Schema

-- roles table
CREATE TABLE roles (
    id UUID PRIMARY KEY,
    name TEXT NOT NULL UNIQUE,
    description TEXT,
    is_system BOOLEAN NOT NULL DEFAULT FALSE,
    created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP
);

-- roles_permissions junction
CREATE TABLE roles_permissions (
    role_id UUID NOT NULL REFERENCES roles(id) ON DELETE CASCADE,
    permission_id UUID NOT NULL REFERENCES permissions(id) ON DELETE CASCADE,
    PRIMARY KEY (role_id, permission_id)
);

-- users_roles junction
CREATE TABLE users_roles (
    user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
    role_id UUID NOT NULL REFERENCES roles(id) ON DELETE CASCADE,
    granted_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
    granted_by UUID REFERENCES users(id),
    PRIMARY KEY (user_id, role_id)
);

Troubleshooting

Role Not Found

1. Verify role exists:

   curl -s -H "Authorization: Bearer $TOKEN" \
       https://api.mantis.local/api/v1/admin/roles | jq '.data[].name'

2. Check ID format - Role IDs are UUIDs

Cannot Modify System Role

System roles are protected:

• admin, operator, viewer are is_system: true
• Cannot update name, description, or permissions
• Cannot delete

Solution: Create a custom role with desired permissions.

Users Retain Access After Role Removal

1. Check for multiple role assignments:

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

2. Check token expiration. Permission checks re-read the database on every request, so removing a permission takes effect immediately. But the roles claim baked into the JWT does not, and that claim is what the admin check reads — so removing someone’s admin role leaves admin-gated routes reachable until their access token expires (1 hour by default). Reset their password to revoke the token outright.

Next Steps

• Permissions - Permission reference
• Users - User management
• Identity Providers - SSO role mappings