> ## Documentation Index
> Fetch the complete documentation index at: https://docs.deploystack.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Role Management System

> Developer guide for managing roles and permissions in DeployStack Backend.

This guide explains how to manage roles and permissions in the DeployStack backend for developers.

## Overview

DeployStack uses a centralized role-based access control (RBAC) system with automatic synchronization between code definitions and database storage.

## Role Definitions

All roles and permissions are defined in a single file:

**`services/backend/src/permissions/index.ts`**

This is the **single source of truth** for all role definitions. To see current roles and their permissions, check this file.

### Role Types

The system supports two types of roles:

* **Global Roles**: System-wide roles (`global_admin`, `global_user`)
* **Team Roles**: Team-specific roles (`team_admin`, `team_user`)

Team roles are assigned within team contexts and work alongside global roles to provide fine-grained access control for team-based resources.

## Database Storage

Roles are stored in the `roles` table with the following structure:

* **`id`** - Role identifier (e.g., 'global\_admin')
* **`name`** - Display name (e.g., 'Global Administrator')
* **`description`** - Role description
* **`permissions`** - JSON array of permission strings
* **`is_system_role`** - Boolean flag for core system roles
* **`created_at`** / **`updated_at`** - Timestamps

User role assignments are stored in the `authUser.role_id` column.

## Automatic Synchronization

The system automatically syncs role permissions from code to database on server startup. The RoleSyncService compares the definitions in `permissions/index.ts` with the database and updates any differences. This ensures the database always matches your code definitions without manual intervention.

## Adding New Roles

### 1. Define the Role

Add your new role to `services/backend/src/permissions/index.ts`:

```typescript theme={null}
export const ROLE_DEFINITIONS = {
  // ... existing roles
  content_moderator: [
    'users.view',
    'content.moderate',
    'reports.view',
  ],
} as const;
```

### 2. Create Database Migration (Optional)

If you want the role available immediately in existing databases, create a migration:

```sql theme={null}
-- Add new role to existing databases
INSERT OR IGNORE INTO `roles` (`id`, `name`, `description`, `permissions`, `is_system_role`, `created_at`, `updated_at`) VALUES 
('content_moderator', 'Content Moderator', 'Manages user content', '[]', 1, strftime('%s', 'now') * 1000, strftime('%s', 'now') * 1000);
```

### 3. Restart Server

The RoleSyncService will automatically populate the role's permissions from your code definition on the next server startup.

## Permission System

### Available Permissions

All permissions are auto-generated from role definitions. The `AVAILABLE_PERMISSIONS` array in `permissions/index.ts` contains all unique permissions across all roles, sorted alphabetically.

### Common Permission Categories

**MCP Installations**

* `mcp.installations.view` - View installation details and configurations
* `mcp.installations.logs.view` - Read server logs from MCP installations (**global\_admin**, **team\_admin** only)
* `mcp.installations.create` - Create new MCP installations
* `mcp.installations.edit` - Modify installation settings
* `mcp.installations.delete` - Delete installations
* `mcp.installations.stats.view` - View installation statistics
* `mcp.installations.instances.view` - View active instances

**MCP Servers**

* `mcp.servers.read` - Browse MCP server catalog
* `mcp.servers.global.view` - View global MCP server definitions
* `mcp.servers.global.create` - Create global MCP servers
* `mcp.servers.global.edit` - Edit global MCP servers
* `mcp.servers.global.delete` - Delete global MCP servers

**Team Management**

* `teams.view` - View team information
* `teams.create` - Create new teams
* `teams.edit` - Modify team settings
* `teams.delete` - Delete teams
* `teams.manage` - Full team management access
* `team.members.view` - View team members
* `team.members.manage` - Add/remove team members

**User Management**

* `users.view` - View user accounts
* `users.create` - Create new users
* `roles.manage` - Assign and modify user roles

**System**

* `system.admin` - System administration access
* `settings.view` - View system settings
* `settings.edit` - Modify system settings
* `settings.delete` - Delete system settings

### Permission Checking

Use the middleware functions for route protection:

```typescript theme={null}
import { requirePermission } from '../middleware/roleMiddleware';

// Require specific permission
fastify.get('/admin-endpoint', {
  preValidation: requirePermission('system.admin')
}, handler);
```

For team-based resources, use team-aware permissions:

```typescript theme={null}
import { requireTeamPermission } from '../middleware/roleMiddleware';

// Team-specific permission checking
fastify.post('/teams/:teamId/resources', {
  preValidation: requireTeamPermission('resources.create')
}, handler);
```

See [API Security Best Practices](/development/backend/api/security) for detailed information about team-aware permissions and security patterns.

### Programmatic Checks

```typescript theme={null}
import { checkUserPermission } from '../middleware/roleMiddleware';

const hasPermission = await checkUserPermission(userId, 'users.edit');
```

## API Endpoints

### Role Management

* `GET /api/roles` - List all roles
* `POST /api/roles` - Create new role
* `PUT /api/roles/:id` - Update role
* `DELETE /api/roles/:id` - Delete role

### User Role Assignment

* `PUT /api/users/:id/role` - Assign role to user
* `GET /api/users/me` - Get current user with role info

## Best Practices

* **Single Source**: Always define roles in `permissions/index.ts`
* **Descriptive Names**: Use clear permission names with dot notation (`users.edit`, `content.moderate`)
* **Minimal Permissions**: Give roles only the permissions they need
* **System Roles**: Mark core roles as `is_system_role: true` to prevent deletion
* **Testing**: Test permission changes in development before deploying

## Security Notes

* System roles cannot be modified or deleted via API
* Users cannot change their own roles
* The last global administrator cannot be deleted
* All permission checks happen server-side