---
title: "Roles and permissions"
description: "Reference workspace and group roles, permissions, and inheritance rules. Use the definitions to assign access to the right people and resources in Alpacon."
---

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

# Roles and permissions

Use [Workspace roles](/use/workspace/settings/roles/) to assign roles and [groups](/use/iam/groups/) to manage server access.

## 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 include workspace privilege roles and roles for specific tasks, while server access is primarily group-based. See [Permission inheritance](#permission-inheritance) for how groups and assigned roles grant server access. You can also create custom roles for fine-grained permission control.

### Built-in roles

The role picker shows the following built-in role names. The member and workspace privilege roles are assigned automatically; the other roles are assigned explicitly.

| Role shown in the console | Assignment | Permissions |
| --- | --- | --- |
| `member` | Every workspace member | Start work sessions, commands, connections, and file transfers within their existing access |
| `admin` | Users set to **Staff** | Manage workspace resources, users, and groups; excludes approval decisions and some privileged actions |
| `superuser` | Users set to **Superuser** | Full workspace control |
| `auditor` | Explicit | Read audit history across the workspace without operational access |
| `operator` | Explicit | Connect to servers, execute commands, transfer files, and manage sessions without IAM or policy administration |
| `security_admin` | Explicit | Manage security and approval policies and direct-access rules; does not grant approval decisions |
| `approver` | Explicit | Approve or reject requests within the assigned scope; does not grant operational access |
| `reviewer` | Explicit | Read audit history, record review decisions, and request standing direct-access entries |
| `service_token:manager` | Explicit | Read applications and read, create, or update their service tokens within the assigned scope; does not grant token deletion |

A regular member receives the `member` role automatically. Access to particular servers still depends on group membership and other assigned roles.

### 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.

To manage roles (Superuser only), go to [Workspace settings > Roles](/use/workspace/settings/roles/).

## Group roles

Each user in a group has one of three roles:

### Owner

**Permissions:**

- Full control over the group
- Add and remove members
- Assign roles to members
- Configure group settings
- Delete the group

**Important:** Each group must have at least one Owner. Cannot remove the last Owner.

### Manager

**Permissions:**

- Add and remove members
- Configure group settings

**Use case:** Delegate group management without giving full control

### Member

**Permissions:**

- Access servers assigned to the group

**Use case:** Standard users who only need server access

## 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

Source: https://docs.alpacax.com/reference/permissions/