---
title: "Manage roles and permissions"
description: "Set server access permissions in Alpacon. Compare user roles, group membership, and feature permissions, then review how those rules affect server work."
---

> Full documentation index: https://docs.alpacax.com/llms.txt

# Manage roles and permissions

<span id="set-permissions" />

# Manage roles and permissions

Manage server access permissions for users and groups in Alpacon.

## Permission model

Alpacon permissions work at two levels:

### 1. User roles (Workspace level)

| Role       | Permissions                                |
| ---------- | ------------------------------------------ |
| User       | Access assigned servers, edit own profile |
| Staff      | Manage users/groups, some workspace settings |
| Superuser  | All permissions, full workspace control    |

### 2. Server access permissions (Group-based)

- Assign groups to servers
- All group members can access the server
- Users can belong to multiple groups

## Role-based access control (RBAC)

Workspace-level permissions (user roles described above) are managed through RBAC. Built-in RBAC roles correspond to the user role levels, while server access is primarily group-based—see [Permission inheritance](#permission-inheritance) below for the full picture. You can also create custom roles for fine-grained permission control.

### Built-in roles

Built-in roles map to the user role levels and are automatically assigned:

| Role      | Auto-assigned when             | Permissions                                |
| --------- | ------------------------------ | ------------------------------------------ |
| admin     | User is set to Staff           | Manage users/groups, some workspace settings |
| superuser | User is set to Superuser       | All permissions, full workspace control    |

Built-in roles are automatically assigned and managed by the system. Regular users (neither staff nor superuser) aren't given a workspace-wide role; their access comes from group membership and any roles directly assigned to them.

### Direct-login review [#direct-login-review]

[External access](/use/audit/governance/external-access/) uses permissions of its own. Every workspace comes with the `reviewer`, `auditor` and `security_admin` roles, which a Superuser assigns explicitly; `admin` is the built-in role Staff members get automatically. This is what each of them holds:

| Permission | What it allows | `reviewer` | `auditor` | `security_admin` | `admin` |
|---|---|---|---|---|---|
| `local_access_event:read` | Read the direct logins recorded on servers | Yes | Yes | Yes | Yes |
| `local_access_finding:read` | Read findings, the period summary, and export evidence | Yes | Yes | Yes | Yes |
| `local_access_finding:dispose` | Record a disposition on a finding, one at a time or in a batch | Yes | — | — | Yes |
| `direct_access_entry:read` | Read the allowed direct access list and the standing-entry requests | Yes | Yes | Yes | Yes |
| `direct_access_entry:request` | Ask for a standing entry | Yes | — | — | Yes |
| `direct_access_entry:create`, `:update`, `:delete` | Add, change and remove standing entries; grant or decline requests (a grant uses `:create`) | — | — | Yes | Yes |
| `local_access_detection:update` | Turn direct-login detection on or off | — | — | Yes | Yes |

These roles work only when assigned workspace-wide. `superuser` holds every permission. For what each role sees in the console, see [Roles and permissions](/use/audit/governance/external-access/#roles).

### Custom roles

Create custom roles to define fine-grained permissions tailored to your organization's needs. Custom roles support two scope levels:

- **Global scope**: The permission applies to all objects of the resource type
- **Object scope**: The permission is limited to specific resource types and objects

### RBAC permissions

Permissions follow the `resource:action` format (e.g., `server:read`, `server:update`). Assign permissions to roles, then assign roles to users or groups. The same vocabulary is used for token scopes, so every permission name is listed in the [scopes reference](/reference/scopes/).

Permission inheritance is additive—a user's effective permissions are the union of all permissions from all assigned roles, including roles inherited through group membership.

## Create and manage roles

Only Superuser members can manage roles in **Workspace settings** → **Roles**.

### Resource-scoped roles

Resource-scoped roles come with Alpacon, like built-in roles, but each one covers a single resource, such as one server or one group, instead of the whole workspace.

Examples include `server:maintainer` and `group:member`. Each role's description in the role list says how it is assigned.

### Role list

The role list displays all roles in the workspace, showing each role's name, description, and created date.

### Create a role

1. Click **New role**
2. Enter the **Name** and **Description** for the role
3. Optionally, pick one or more **Permission templates** to fill in the role's permissions
4. Save

A template is one of the presets in the [scopes reference](/reference/scopes/), and a role built from it gets every scope the template lists, whichever extensions are on. A role created without a template starts with no permissions. Assign permissions, users, and groups from the role detail page, where you can also change the permissions a template filled in.

### Delete a role

1. Navigate to the role detail page
2. Go to the **Settings** tab
3. Click **Delete role**
4. Confirm the deletion

### Role detail page

The role detail page has four tabs: **Permissions**, **User assignments**, **Group assignments**, and **Settings**.

#### Permissions tab

Manage permissions assigned to this role. Each permission follows the `resource:action` format (e.g., `server:read`, `server:update`); the full list is in the [scopes reference](/reference/scopes/).

The permissions list shows the permission name, and whether it is scoped to a specific resource type and object.

You can search permissions using the search bar and filter by **All** or **Assigned** status.

**Assign a permission:**

1. Click **Assign permission**
2. Select a **Permission** from the dropdown
3. Optionally, check **Limit to specific resource** to restrict the permission to a specific resource type and object:
   - Select a **Resource type** from the dropdown
   - Select one or more **Object** entries from the checkbox list
   - If no objects are available for the selected resource type, the permission applies to all objects of that type
4. Save

**Remove a permission:**

Select the assignment and click **Remove assignment** to remove it from this role.

#### User assignments tab

Manage users assigned to this role. The list shows each user's name, email, and scope information.

**Assign a user:**

1. Click **Assign user**
2. Select a **User** from the dropdown
3. Optionally, configure the **Scope** to limit this role to a specific resource
4. Save

**Remove a user assignment:**

Select the assignment and click **Remove assignment** to remove it.

A Superuser's `admin` assignment cannot be removed on its own—remove their `superuser` assignment first.

#### Group assignments tab

Manage groups assigned to this role. When a role is assigned to a group, all members of that group inherit the role's permissions.

**Assign a group:**

1. Click **Assign group**
2. Select a **Group** from the dropdown
3. Optionally, configure the **Scope** to limit this role to a specific resource
4. Save

**Remove a group assignment:**

Select the assignment and click **Remove assignment** to remove it.

#### Settings tab

Edit the role's name and description, or delete the role.

- **Name**: A unique name for this role
- **Description**: An optional description of the role's purpose

Click **Save** to apply changes, or **Delete role** to permanently remove the role and all its assignments.

## Set user roles

**How to change:**
1. Select user in **IAM** > **Users**
2. Click **Edit**
3. Change **Role**
4. Click **Save**

**Required permission:** Staff or Superuser

Details: [Manage users](/use/iam/users/manage/)

## Configure server access

### Access control via groups

**Step 1: Create groups**
- [Create groups](/use/iam/groups/create/)

**Step 2: Add users to groups**
- [Assign users](/use/iam/groups/assign-users/)

**Step 3: Assign groups to servers**
- [Server group management](/use/servers/groups/)

### Set individual server permissions

1. Select server in **Servers** page
2. Click **Edit**
3. Select Assigned groups
4. Click **Save**

All members of selected groups can access the server.

## Feature permissions

### Websh (Terminal)

Terminal access to servers assigned to group:
- Login as IAM username
- sudo access available

### WebFTP (File management)

File upload/download to servers assigned to group:
- Access user home directory
- Access other directories based on permissions

### MFA required actions

On Enterprise, Superusers can select these actions under **Policies > Authentication** to require fresh MFA. None are selected by default:

- **Server actions**: upgrading or restarting the agent, and installing alpamon-pam
- **Web terminal**: connecting as a system account other than your own
- **Code editor**: opening the editor as a system account other than your own
- **File transfer**: transferring files as a system account other than your own
- **Command**: running a command as a system account other than your own
- **Approval decisions**: approving or rejecting a request as a reviewer

Configure: [Policies > Authentication](/use/policies/authentication/)

## Permission examples

### Example 1: Development team server access

```
Group: developers
Members: user1 (User), user2 (User), user3 (Staff)

Servers: dev-server-01, dev-server-02
Assigned groups: developers

Result: user1, user2, user3 all access both servers
```

### Example 2: Production server restriction

```
Group: senior-engineers
Members: user3 (Staff), user4 (Superuser)

Server: prod-server-01
Assigned groups: senior-engineers

Result: Only user3, user4 access production server
```

## Permission inheritance

**Multiple group membership:**
- If user belongs to groups A and B
- Can access all servers assigned to A and B

**Roles and groups:**
- Superuser (RBAC `superuser`) and Staff (RBAC `admin`) members access all servers, without group assignment

**Server maintainers and object-scoped roles:**
- A server's maintainer can access it even without group assignment. A maintainer is a user who holds the `server:maintainer` role scoped to that server, either directly or as a member of a group the role is assigned to. An admin grants or revokes the role through the RBAC role API; registering a server or becoming its owner does not grant it. A server registered while Alpacon still granted the role automatically keeps that grant for the user who registered it. Assigned workspace-wide or scoped to a server group, the role does not make anyone a maintainer
- A maintainer can also connect as other existing accounts on the server, like an owner or manager of an assigned group
- Assigning a user or group a custom role that grants `server:read`, scoped to one server or to one of its groups (object scope), reaches that server the same way
- A user reached this way can also use the server as a work session or sudo policy target, like a group member

**Role inheritance through groups:**
- When a role is assigned to a group, all members of that group inherit the role's permissions
- A user's effective permissions are the union of all directly assigned roles and group-inherited roles

## Security best practices

**Principle of least privilege:**
- Grant minimum required permissions
- Regularly review and adjust permissions

**Use groups:**
- Manage permissions via groups rather than individual users
- Separate groups by environment, project

**Limit Superusers:**
- Keep Superuser role to minimum
- Grant only to trusted administrators

## Audit logs

All permission changes are logged:
- Who changed permissions and when
- Which user/group permissions were changed

## Related docs

- [Manage users](/use/iam/users/manage/)
- [Manage groups](/use/iam/groups/manage/)
- [Server group management](/use/servers/groups/)
- [Workspace settings](/use/workspace/settings/)

Source: https://docs.alpacax.com/use/workspace/settings/roles/