---
title: "Scopes"
description: "Choose Alpacon scopes for roles and tokens. Check resource actions, ACL restrictions, console-only operations, and permissions for work sessions and users."
---

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

# Scopes

A scope is one entry in the Alpacon permission vocabulary. It names a resource and an action allowed on that resource, such as reading servers or running a command. The same vocabulary does two jobs: it is what a role grants to a user or a group, and it is what you choose from when you issue an API token or a service token. This page lists every scope Alpacon defines, grouped by the part of the product it belongs to, so you can give a credential the smallest set it actually needs.

The scope picker in the console and `alpacon token scopes` show the subset you can grant right now. This page explains what each one means.

## What a scope is

A scope has two parts joined by a colon: the resource it applies to, and the action it allows on that resource. `server:read` allows reading servers. `command:create` allows running a command on one.

The vocabulary is flat on purpose. There is no nesting, so `server:read` and `session:read` are unrelated entries rather than a hierarchy.

A scope on a credential is a limit, not a grant. Putting `server:delete` on a token does not give you the ability to delete servers; it lets the token use an ability your roles already give you. A scope your roles do not include cannot go on the token at all.

Three different things in Alpacon are called a scope. This page is about the first one.

| Term | What it is |
|---|---|
| **Scope** (this page) | A `resource:action` entry. Roles, API tokens, and service tokens all use it. |
| **Work session scope** | One of `websh`, `command`, `webftp`, `tunnel`, `editor`, `sudo`: which kinds of activity an approved [work session](/use/work-sessions/) allows. Set with `alpacon work-session create --scope`. |
| **Permission scope** | In [role management](/use/workspace/settings/roles/), whether a permission applies workspace-wide or only to specific objects. |

## How a scope is checked

**When the credential is issued.** Every scope you select is checked against what your own roles give you, so you cannot put a scope on a token that you do not hold yourself. There is no administrator exception: a workspace superuser can select any scope because the superuser role holds the full wildcard, and that goes through the same check as everyone else. Only workspace-wide permissions count here. A permission you hold on one specific server or group does not let you put that scope on a token.

For a **service token**, the same check runs against the roles of the [application](/use/iam/applications/) the token belongs to, not against yours.

**For the rest of its life.** The scopes stored on a credential are a claim, not a standing grant. What the credential can actually do is that stored set bounded by what its owner may confer *right now*, so authority the owner loses stops flowing through every credential minted from it. The effect is immediate and needs no reissue. It only ever narrows: a widened role never widens a credential that already exists.

Two consequences worth planning around. Reducing someone's role reduces their tokens at the same moment, with no notification to whoever is using them, so a pipeline can start failing on a permission change nobody connected to it. And the stored list the console shows you is the claim, which can be wider than what the credential currently buys.

**On each request.** A request made with a token succeeds only if the token holds the scope for that operation. Requests you make in the console after signing in are not limited by token scopes.

**Two separate questions.** A scope answers *what kind of operation* is allowed. An ACL answers *which objects* it may be performed on. Both apply, and the Object narrowing column in the catalog below tells you which kind of ACL a resource answers to:

- **Server ACL** decides which servers a credential may reach. For a service token this is the whole of its server visibility: with no entries at all, it sees no servers.
- **Command ACL** decides which commands it may run.
- **File ACL** decides which paths it may transfer.

A resource showing `—` in that column is not narrowed by an ACL.

## Scope format

| Form | Example | Meaning |
|---|---|---|
| `resource:action` | `server:read` | One action on one resource |
| `resource:*` | `server:*` | Every action on one resource |
| `*:action` | `*:read` | One action on every resource |
| `*` | `*` | Everything |

- Lowercase only. A resource or action name starts with a letter and may contain letters, digits, underscores, and hyphens.
- Exactly one colon, and at most 64 characters.
- Partial patterns are not accepted. `server:*` is valid, `ser*:read` is not.
- A wildcard has to cover at least one scope that exists, so a misspelling like `sever:*` is rejected instead of quietly accepted.
- A wildcard is accepted only when your own permissions cover that wildcard. Holding every individual `server:` action is not the same as holding `server:*`—asking for `server:*` requires that you hold `server:*` or `*` yourself. Personal API tokens cannot hold `*`, even for a Superuser. A service token may hold it only within its application's permissions.

## Standard actions

Most resources use the same four action names.

| Action | Meaning |
|---|---|
| `create` | Create a new one. |
| `read` | List them, and read one in detail. |
| `update` | Modify an existing one. |
| `delete` | Delete one. |

`read` covers both listing and reading a single item, and `update` covers both a full replacement and a partial change. Where a resource gives one of these four names a meaning of its own—`command:create` runs a command, `session:create` opens a terminal—it appears in that resource's own table instead of here.

## Presets

A preset is a named bundle of scopes for a common job. Picking one saves you from assembling the parts by hand.

The tables below list every scope a preset carries. Three of them carry a scope that cannot go on a credential, so on an API token or a service token those presets apply what is left—each one says so. Used for a role, a preset always applies everything it lists, whichever extensions are on.

**Terminal access** (`terminal_access`)

Open a Websh terminal on a server, run commands in it, and read the session history.

| Resource | Action |
|---|---|
| `server` | `read` |
| `session` | `create` · `read` · `close` · `refresh` |
| `userchannel` | `create` · `read` · `close` |
| `command` | `read` · `create` · `chunks` |

On a credential, `session:create` and `userchannel:create` are left out. *Why a scope may not be available* below says why.

**Command execution** (`command_execute`)

Run commands on servers with `alpacon exec` and read the output as it streams back.

| Resource | Action |
|---|---|
| `server` | `read` |
| `command` | `create` · `read` · `chunks` · `purpose` |
| `event_session` | `create` · `read` |
| `event_subscription` | `create` · `read` |

**Command history** (`command_read`)

Read command history and output without being able to run anything new.

| Resource | Action |
|---|---|
| `server` | `read` |
| `command` | `read` · `chunks` |

**File upload** (`file_upload`)

Send files to servers with `alpacon cp local server:`.

| Resource | Action |
|---|---|
| `server` | `read` |
| `uploaded_file` | `create` · `upload` · `status` · `bulk` · `bulk_upload` · `read` |

**File download** (`file_download`)

Fetch files from servers with `alpacon cp server: local`.

| Resource | Action |
|---|---|
| `server` | `read` |
| `downloaded_file` | `create` · `download` · `status` · `bulk` · `read` |

**File transfer** (`file_transfer`)

Both directions, through either `alpacon cp` or WebFTP in the browser.

| Resource | Action |
|---|---|
| `server` | `read` |
| `uploaded_file` | `create` · `upload` · `status` · `bulk` · `bulk_upload` · `read` |
| `downloaded_file` | `create` · `download` · `status` · `bulk` · `read` |
| `ftp_session` | `create` · `read` · `close` |

On a credential, `ftp_session:create` is left out. *Why a scope may not be available* below says why.

**Tunnel session** (`tunnel_connect`)

Open tunnel sessions to servers with `alpacon tunnel`.

| Resource | Action |
|---|---|
| `server` | `read` |
| `tunnel_session` | `create` · `read` · `reconnect` · `close` |

On a credential, `tunnel_session:create` and `tunnel_session:reconnect` are left out, which leaves listing and closing but not opening. *Why a scope may not be available* below says why.

**Monitoring** (`monitoring`)

Read server resource usage, read a server's collection profile, and view and acknowledge alerts. Alert rules are readable but not editable. On an API token or a service token, the whole preset disappears when the Metrics extension is off, even though two of its scopes aren't themselves extension-gated: `alert` and `server:collection_profile` stay selectable on their own, or through another preset, whichever way the extension is set. A role can still be built from it, with every scope below.

| Resource | Action |
|---|---|
| `server` | `read` · `collection_profile` |
| `metric` | `read` · `top` |
| `alert` | `read` · `acknowledge` |
| `alert_rule` | `read` |

**Certificate management** (`cert_management`)

Request and track certificates from the internal certificate authority. On an API token or a service token, the whole preset disappears when the Private SSL extension is off. A role can still be built from it, with every scope below.

| Resource | Action |
|---|---|
| `authority` | `read` |
| `sign_request` | `read` · `create` · `submit` |
| `certificate` | `read` |
| `revoke_request` | `read` · `create` |

**Group management** (`group_management`)

Create and change groups, and manage which users belong to them.

| Resource | Action |
|---|---|
| `group` | `read` · `create` · `update` · `delete` |
| `membership` | `read` · `create` · `update` · `delete` |

**Read-only** (`read_only`)

Read servers, commands, events, sessions, metrics, alerts, and transfer records. Workspace administration and extension resources are not included. On an API token or a service token, the `metric` and `alert_rule` rows drop out of this preset on a workspace without the Metrics extension. A role built from it keeps them.

| Resource | Action |
|---|---|
| `server` | `read` · `collection_profile` |
| `command` | `read` |
| `event` | `read` |
| `session` | `read` |
| `userchannel` | `read` |
| `tunnel_session` | `read` |
| `ftp_session` | `read` |
| `uploaded_file` | `read` |
| `downloaded_file` | `read` |
| `metric` | `read` |
| `alert` | `read` |
| `alert_rule` | `read` |

Presets are expanded into individual scopes when the credential is created, and the credential stores those scopes. Editing a preset later therefore does not change credentials that already exist. Presets can only be used while creating a credential, not while editing one.

## Why a scope may not be available

If the console or the CLI does not offer a scope you expected, one of these is usually why.

**Your roles do not include it.** The picker shows only what you could grant. Ask a workspace administrator for the role that carries it.

**The workspace extension is not enabled.** On an API token or a service token, resources belonging to IP, DNS, Proxy, Private SSL, Firewall, and Metrics appear only when that extension is turned on. Metrics gates `metric`, `alert_rule`, and `rule_override`—not `alert`, which core disk and offline alerts also use, or `server:collection_profile`, which reports the extension's status and works whether it's on or off.

**It is reserved.** These scopes are deliberately left out of the `admin` role:

- Closing a session that belongs to someone else: `session:force_close`, `tunnel_session:force_close`, `ftp_session:force_close`
- Closing sessions: `session:close`, `tunnel_session:close`, `ftp_session:close`, `userchannel:close`
- Deciding approval requests: `approval_request:approve`, `approval_request:reject`
- Emergency access on a service token: `service_token:break_glass`
- Deleting a group: `group:delete`

They come from a more specific role instead. The `operator` role covers closing sessions, the `approver` role covers deciding approval requests, and a workspace superuser holds everything.

**It cannot be put on a credential.** A few scopes exist and are offered to roles, but a token cannot carry them. Which tokens this applies to depends on the scope. Your roles are not the reason, and asking for another one will not help.

Use a [service token](/reference/api/service-tokens/) for automated command execution and file transfers. Personal tokens cannot be issued execution scopes.

- Opening a terminal, a tunnel, or a WebFTP session, or letting someone else into one: `session:create`, `session:share`, `session:invite`, `userchannel:create`, `userchannel:update`, `tunnel_session:create`, `tunnel_session:reconnect`, `ftp_session:create`. These actions need a person present at a keyboard, and a recent MFA check where your workspace requires one. A token has nobody behind it, so it is refused with `auth_interactive_channel_requires_presence` when it tries, and the scope would open nothing. Use the console for interactive work. For automation, use the presets for the operation itself: **Command execution** to run commands, and **File upload** and **File download** to transfer files.
- Registering a server, on a **personal** API token only: `server:register`. Register a server with a registration token instead—create one under the server's registration page. A registration token is listed and revoked alongside the workspace's other [server registration tokens](/use/servers/register/tokens/), and can place the new server into the groups you chose. A personal token is not on that list, and cannot choose the new server's groups. A service token may hold `server:register`, because a service token belongs to an application and is managed on its own page.
- Attaching a service token to an AI agent: `ai_agent:attach`. This scope cannot be included in personal API tokens or service tokens.

A preset drops scopes that cannot be issued to that token kind and keeps the rest. Personal tokens also exclude the execution scopes listed in the [personal token reference](/reference/api/tokens/). A role keeps every scope in the preset.

**Tokens cannot perform console-only actions.** Changing approval policies (`approval_policy:create`, `approval_policy:update`, `approval_policy:delete`) and creating sudo policies (`sudo_policy:create`) require the console. A request made with a token is refused before its scope is checked. `approval_policy:read`, `sudo_policy:update`, and `sudo_policy:delete` can still be put on a token.

Personal API tokens cannot hold full access (`*`); requesting it is refused. Service tokens may hold `*` within the application's permissions, but console-only and session-only routes still refuse them.

## All resources

| Resource | Area | Actions | Object narrowing |
|---|---|---|---|
| [`server`](#server) | Servers | 25 | Server |
| [`note`](#note) | Servers | 4 | Server |
| [`registration_token`](#registration_token) | Servers | 3 | — |
| [`registration_method`](#registration_method) | Servers | 2 | — |
| [`proc`](#proc) | Servers | 5 | Server |
| [`backhaul_session`](#backhaul_session) | Servers | 1 | Server |
| [`session`](#session) | Sessions and terminals | 13 | Server |
| [`session_analysis`](#session_analysis) | Sessions and terminals | 2 | — |
| [`userchannel`](#userchannel) | Sessions and terminals | 5 | Server |
| [`tunnel_session`](#tunnel_session) | Sessions and terminals | 5 | Server |
| [`work_session`](#work_session) | Sessions and terminals | 14 | Server |
| [`ftp_session`](#ftp_session) | File transfer | 6 | Server |
| [`uploaded_file`](#uploaded_file) | File transfer | 7 | Server, File |
| [`downloaded_file`](#downloaded_file) | File transfer | 6 | Server, File |
| [`command`](#command) | Commands and events | 5 | Server, Command |
| [`approved_file_execution`](#approved_file_execution) | Commands and events | 2 | — |
| [`event`](#event) | Commands and events | 1 | Server |
| [`local_access_event`](#local_access_event) | Commands and events | 1 | Server |
| [`local_access_finding`](#local_access_finding) | Commands and events | 2 | Server |
| [`direct_access_entry`](#direct_access_entry) | Commands and events | 5 | — |
| [`local_access_detection`](#local_access_detection) | Commands and events | 1 | — |
| [`event_session`](#event_session) | Commands and events | 4 | — |
| [`event_subscription`](#event_subscription) | Commands and events | 4 | — |
| [`cloud_account`](#cloud_account) | Cloud | 14 | — |
| [`cloud_connection_method`](#cloud_connection_method) | Cloud | 1 | — |
| [`cloud_instance`](#cloud_instance) | Cloud | 6 | — |
| [`installation_job`](#installation_job) | Cloud | 1 | — |
| [`network`](#network) | IP management | 4 | — |
| [`subnet`](#subnet) | IP management | 4 | — |
| [`pool`](#pool) | IP management | 4 | — |
| [`device`](#device) | IP management | 4 | — |
| [`dhcp_server`](#dhcp_server) | IP management | 6 | Server |
| [`lease`](#lease) | IP management | 3 | Server |
| [`dhcp_session`](#dhcp_session) | IP management | 1 | Server |
| [`zone`](#zone) | DNS | 4 | — |
| [`record`](#record) | DNS | 4 | — |
| [`dns_view`](#dns_view) | DNS | 4 | — |
| [`dns_server`](#dns_server) | DNS | 6 | Server |
| [`domain_group`](#domain_group) | Proxy | 4 | — |
| [`domain`](#domain) | Proxy | 4 | — |
| [`access_policy`](#access_policy) | Proxy | 4 | — |
| [`access_rule`](#access_rule) | Proxy | 4 | — |
| [`proxy_profile`](#proxy_profile) | Proxy | 4 | — |
| [`proxy_server`](#proxy_server) | Proxy | 6 | Server |
| [`authority`](#authority) | Private SSL | 7 | Server |
| [`sign_request`](#sign_request) | Private SSL | 9 | — |
| [`certificate`](#certificate) | Private SSL | 2 | — |
| [`revoke_request`](#revoke_request) | Private SSL | 8 | — |
| [`package`](#package) | Packages | 4 | — |
| [`package_entry`](#package_entry) | Packages | 4 | — |
| [`security_group`](#security_group) | Firewall | 9 | — |
| [`security_group_assignment`](#security_group_assignment) | Firewall | 5 | Server |
| [`security_group_snapshot`](#security_group_snapshot) | Firewall | 5 | — |
| [`firewall_chain`](#firewall_chain) | Firewall | 4 | — |
| [`firewall_rule`](#firewall_rule) | Firewall | 5 | — |
| [`alert_rule`](#alert_rule) | Monitoring and audit | 4 | — |
| [`rule_override`](#rule_override) | Monitoring and audit | 4 | Server |
| [`metric`](#metric) | Monitoring and audit | 2 | Server |
| [`alert`](#alert) | Monitoring and audit | 2 | Server |
| [`activity`](#activity) | Monitoring and audit | 2 | — |
| [`activity_report`](#activity_report) | Monitoring and audit | 2 | — |
| [`role_audit_log`](#role_audit_log) | Monitoring and audit | 1 | — |
| [`command_acl`](#command_acl) | Access control lists | 7 | — |
| [`server_acl`](#server_acl) | Access control lists | 6 | — |
| [`file_acl`](#file_acl) | Access control lists | 7 | — |
| [`approval_policy`](#approval_policy) | Approvals and sudo | 4 | — |
| [`approval_request`](#approval_request) | Approvals and sudo | 8 | — |
| [`sudo_policy`](#sudo_policy) | Approvals and sudo | 4 | — |
| [`sudo_policy_request`](#sudo_policy_request) | Approvals and sudo | 2 | — |
| [`sudo_grant`](#sudo_grant) | Approvals and sudo | 2 | — |
| [`webhook`](#webhook) | Notifications | 4 | — |
| [`notification`](#notification) | Notifications | 3 | — |
| [`slack_installation`](#slack_installation) | Notifications | 3 | — |
| [`slack_user_mapping`](#slack_user_mapping) | Notifications | 5 | — |
| [`workspace`](#workspace) | Workspace and IAM | 2 | — |
| [`preferences`](#preferences) | Workspace and IAM | 2 | — |
| [`user`](#user) | Workspace and IAM | 5 | — |
| [`group`](#group) | Workspace and IAM | 4 | — |
| [`membership`](#membership) | Workspace and IAM | 4 | — |
| [`ai_agent`](#ai_agent) | Workspace and IAM | 2 | — |
| [`application`](#application) | Workspace and IAM | 4 | — |
| [`service_token`](#service_token) | Workspace and IAM | 7 | — |

## Servers

### server

Server records: registration, fleet listing, per-server detail, and grouping. Narrowed by Server ACL. See [Server management](/use/servers/).

Standard meanings: <a id="server-read"></a>`read` · <a id="server-update"></a>`update`

| Action | What it permits |
|---|---|
| <a id="server-access"></a>`access` | Server access |
| <a id="server-actions"></a>`actions` | Run a built-in server action |
| <a id="server-attach_rule"></a>`attach_rule` | Attach an alert rule to the server |
| <a id="server-collection_profile"></a>`collection_profile` | Read the server's [collection profile](/reference/api/servers/servers/#collection-profile)—what it collects, how often, and what it doesn't |
| <a id="server-create"></a>`create` | Add a server to the workspace |
| <a id="server-delete"></a>`delete` | Remove a server from the workspace |
| <a id="server-detach_rule"></a>`detach_rule` | Detach an alert rule from the server |
| <a id="server-groups"></a>`groups` | Read the server's system groups |
| <a id="server-hexagon"></a>`hexagon` | Read the fleet status overview |
| <a id="server-info"></a>`info` | Read the server's system information |
| <a id="server-interfaces"></a>`interfaces` | Read the server's network interfaces |
| <a id="server-mute"></a>`mute` | Mute or unmute the server's alerts |
| <a id="server-os"></a>`os` | Read the server's OS version |
| <a id="server-os_distribution"></a>`os_distribution` | Read OS distribution statistics across servers |
| <a id="server-packages"></a>`packages` | Read the packages installed on the server |
| <a id="server-register"></a>`register` | Let a server enroll itself |
| <a id="server-reserved_commands"></a>`reserved_commands` | Read commands scheduled to run later |
| <a id="server-search_records"></a>`search_records` | Record search |
| <a id="server-star"></a>`star` | Read and set the favorite marker |
| <a id="server-time"></a>`time` | Read the server's system time |
| <a id="server-users"></a>`users` | Read the server's system users |

### note

Free-form notes attached to a server. Narrowed by Server ACL. See [Managing a server](/use/servers/manage/).

Standard meanings: <a id="note-create"></a>`create` · <a id="note-delete"></a>`delete` · <a id="note-read"></a>`read` · <a id="note-update"></a>`update`

### registration_token

Registration tokens that let a new server enroll itself. See [Server registration tokens](/use/servers/register/tokens/).

Standard meanings: <a id="registration_token-delete"></a>`delete` · <a id="registration_token-read"></a>`read`

| Action | What it permits |
|---|---|
| <a id="registration_token-create"></a>`create` | Create a registration token |

### registration_method

The registration methods offered when adding a server, and the generated setup guide. See [Registering a server](/use/servers/register/).

Standard meanings: <a id="registration_method-read"></a>`read`

| Action | What it permits |
|---|---|
| <a id="registration_method-guide"></a>`guide` | Generate the setup guide for the chosen method |

### proc

System accounts discovered on managed servers, and how they map to Alpacon users. Narrowed by Server ACL. See [Account selection](/use/work-sessions/account-selection/).

Standard meanings: <a id="proc-read"></a>`read`

| Action | What it permits |
|---|---|
| <a id="proc-adopt"></a>`adopt` | Link a discovered system account to an Alpacon user |
| <a id="proc-coverage"></a>`coverage` | Read account coverage per server and across the fleet |
| <a id="proc-resolve"></a>`resolve` | Settle a discovered account that is waiting on a decision |
| <a id="proc-unadopt"></a>`unadopt` | Unlink a system account from its Alpacon user |

### backhaul_session

Agent connection sessions between a managed server and Alpacon. Narrowed by Server ACL.

Standard meanings: <a id="backhaul_session-read"></a>`read`

## Sessions and terminals

### session

Websh terminal sessions: opening, sharing, closing, and reading the recorded transcript. Narrowed by Server ACL. See [Websh sessions](/use/work-sessions/terminal/sessions/).

Standard meanings: <a id="session-delete"></a>`delete` · <a id="session-read"></a>`read` · <a id="session-update"></a>`update`

| Action | What it permits |
|---|---|
| <a id="session-analysis"></a>`analysis` | Read the AI analysis of a session |
| <a id="session-analyze"></a>`analyze` | Start AI analysis of a session |
| <a id="session-close"></a>`close` | Close a session |
| <a id="session-create"></a>`create` | Open a Websh terminal session |
| <a id="session-force_close"></a>`force_close` | Close a session that belongs to someone else |
| <a id="session-invite"></a>`invite` | Invite people to the session by email |
| <a id="session-records"></a>`records` | Read the session transcript |
| <a id="session-refresh"></a>`refresh` | Redraw the terminal of an open session |
| <a id="session-search_records"></a>`search_records` | Search within the session transcript |
| <a id="session-share"></a>`share` | Create a share link for the session |

### session_analysis

AI analysis results produced for terminal sessions. See [Session analysis](/use/audit/events/websh/analysis/).

Standard meanings: <a id="session_analysis-read"></a>`read`

| Action | What it permits |
|---|---|
| <a id="session_analysis-aggregate"></a>`aggregate` | Read analysis results aggregated across sessions |

### userchannel

Individual viewer connections within a terminal session, including shared and invited ones. Narrowed by Server ACL. See [Websh sessions](/use/work-sessions/terminal/sessions/).

Standard meanings: <a id="userchannel-delete"></a>`delete` · <a id="userchannel-read"></a>`read` · <a id="userchannel-update"></a>`update`

| Action | What it permits |
|---|---|
| <a id="userchannel-close"></a>`close` | Close a viewer connection |
| <a id="userchannel-create"></a>`create` | Join a terminal session |

### tunnel_session

Tunnel sessions used by the editor and by port forwarding. Narrowed by Server ACL. See [Editor sessions](/use/work-sessions/editor/sessions/).

Standard meanings: <a id="tunnel_session-read"></a>`read`

| Action | What it permits |
|---|---|
| <a id="tunnel_session-close"></a>`close` | Close a session |
| <a id="tunnel_session-create"></a>`create` | Open a tunnel session |
| <a id="tunnel_session-force_close"></a>`force_close` | Close a session that belongs to someone else |
| <a id="tunnel_session-reconnect"></a>`reconnect` | Reconnect the tunnel session |

### work_session

Work sessions: the time-boxed, approved access window and everything decided inside it. Narrowed by Server ACL. See [Work sessions](/use/work-sessions/).

The [work-session API](/reference/api/work-sessions/) also checks who is calling. `approve` and `reject` work only in the web console, so these scopes open nothing on a token. `revoke` works with a token only when its owner is a Superuser. The `cancel`, `live_snapshot`, and `acknowledge-recommendations` routes refuse tokens with granular scopes. A service token cannot create a session; a person creates a session assigned to it.

Standard meanings: <a id="work_session-read"></a>`read` · <a id="work_session-update"></a>`update`

| Action | What it permits |
|---|---|
| <a id="work_session-activate"></a>`activate` | Move an approved session to active |
| <a id="work_session-analyze"></a>`analyze` | Start AI analysis of a session |
| <a id="work_session-approve"></a>`approve` | Approve the session's request in the web console only; unavailable to tokens |
| <a id="work_session-candidate_target_accounts"></a>`candidate_target_accounts` | List candidate accounts on the named servers (also requires `proc:read`) |
| <a id="work_session-complete"></a>`complete` | Complete a running session |
| <a id="work_session-create"></a>`create` | Request a work session |
| <a id="work_session-extend"></a>`extend` | Extend a running session's expiry |
| <a id="work_session-reject"></a>`reject` | Reject the session's request in the web console only; unavailable to tokens |
| <a id="work_session-resolve_target_account"></a>`resolve_target_account` | Check one candidate account before creating a session (also requires `proc:read`) |
| <a id="work_session-revoke"></a>`revoke` | Force-terminate a session; a token's owner must be a Superuser |
| <a id="work_session-suggest_scopes"></a>`suggest_scopes` | Get recommended scope presets before creating a session |
| <a id="work_session-timeline"></a>`timeline` | Read the session timeline |

## File transfer

### ftp_session

WebFTP browsing sessions on a server. Narrowed by Server ACL. See [WebFTP](/use/work-sessions/files/).

Standard meanings: <a id="ftp_session-delete"></a>`delete` · <a id="ftp_session-read"></a>`read` · <a id="ftp_session-update"></a>`update`

| Action | What it permits |
|---|---|
| <a id="ftp_session-close"></a>`close` | Close a session |
| <a id="ftp_session-create"></a>`create` | Open a WebFTP session |
| <a id="ftp_session-force_close"></a>`force_close` | Close a session that belongs to someone else |

### uploaded_file

Files sent to a server, whether through WebFTP or `alpacon cp`. Narrowed by Server, File ACL. See [Uploading files](/use/work-sessions/files/upload/).

Standard meanings: <a id="uploaded_file-read"></a>`read`

| Action | What it permits |
|---|---|
| <a id="uploaded_file-bulk"></a>`bulk` | Create several transfers in one request |
| <a id="uploaded_file-bulk_upload"></a>`bulk_upload` | Start several transfers in one request |
| <a id="uploaded_file-create"></a>`create` | Start sending a file to a server |
| <a id="uploaded_file-download"></a>`download` | Download the transferred file |
| <a id="uploaded_file-status"></a>`status` | Read the transfer status |
| <a id="uploaded_file-upload"></a>`upload` | Start the transfer to the server |

### downloaded_file

Files fetched from a server, whether through WebFTP or `alpacon cp`. Narrowed by Server, File ACL. See [Downloading files](/use/work-sessions/files/download/).

Standard meanings: <a id="downloaded_file-read"></a>`read`

| Action | What it permits |
|---|---|
| <a id="downloaded_file-bulk"></a>`bulk` | Create several transfers in one request |
| <a id="downloaded_file-create"></a>`create` | Start fetching a file from a server |
| <a id="downloaded_file-download"></a>`download` | Download the fetched file |
| <a id="downloaded_file-status"></a>`status` | Read the transfer status |
| <a id="downloaded_file-upload"></a>`upload` | Receive the file coming back from the server |

## Commands and events

### command

Commands run on servers, and their output. Narrowed by Server, Command ACL. See [Command events](/use/audit/events/commands/).

| Action | What it permits |
|---|---|
| <a id="command-chunks"></a>`chunks` | Read command output in chunks |
| <a id="command-create"></a>`create` | Run a command on a server |
| <a id="command-delete"></a>`delete` | Delete a command record |
| <a id="command-purpose"></a>`purpose` | State why a held command is being run, so it is judged again |
| <a id="command-read"></a>`read` | Read command history and output |

### approved_file_execution

Standing approvals for a script: when an approver approves a held file execution and lets the same unchanged script run again without a new approval, that permission is kept here. A grant can't be created through this resource; it comes only from an approver's decision. A revoked grant stays readable.

Standard meanings: <a id="approved_file_execution-read"></a>`read`

| Action | What it permits |
|---|---|
| <a id="approved_file_execution-revoke"></a>`revoke` | Stop a grant from admitting further runs |

### event

The event log that records what happened on a server. Narrowed by Server ACL. See [Event audit](/use/audit/events/).

Standard meanings: <a id="event-read"></a>`read`

### local_access_event

Login events recorded when someone connects to a server without going through Alpacon. For a signed-in member, the [External access read scope](/use/audit/governance/external-access/#read-scope) determines which servers' events they can read. A personal API token also needs the corresponding scope. A service token needs the scope and reads only servers within its Server ACL.

Standard meanings: <a id="local_access_event-read"></a>`read`

### local_access_finding

Findings group direct logins for review. For a signed-in member, the [External access read scope](/use/audit/governance/external-access/#read-scope) determines which servers' findings they can read, even when the role applies workspace-wide. A personal API token also needs this scope. A service token needs the scope and reads only servers within its Server ACL. Tokens can list and read findings. The period summary, evidence export and recording a disposition require a signed-in session.

| Action | What it permits |
|---|---|
| <a id="local_access_finding-read"></a>`read` | List and open findings within the reader’s server reach |
| <a id="local_access_finding-dispose"></a>`dispose` | Record a disposition on a finding, one at a time or in a batch |

### direct_access_entry

The allowed direct access list: standing entries for expected direct logins, and the requests for them. See [The allowed direct access list](/use/audit/governance/external-access/review/#allowed-direct-access). `create` also covers granting or declining a request. Every action except `read` needs a person signed in to the console, and `create`, `update` and `delete` also ask for MFA verification.

Standard meanings: <a id="direct_access_entry-create"></a>`create` · <a id="direct_access_entry-delete"></a>`delete` · <a id="direct_access_entry-read"></a>`read` · <a id="direct_access_entry-update"></a>`update`

| Action | What it permits |
|---|---|
| <a id="direct_access_entry-request"></a>`request` | Ask a policy owner for a standing entry |

### local_access_detection

The workspace's direct-login detection switch. See [Turn on detection](/use/audit/governance/external-access/#turn-on-detection). Changing it needs a person signed in to the console and MFA verification, so a token holding this scope can't use it.

| Action | What it permits |
|---|---|
| <a id="local_access_detection-update"></a>`update` | Turn direct-login detection on or off |

### event_session

Live event streams that a client subscribes to while a command runs.

Standard meanings: <a id="event_session-create"></a>`create` · <a id="event_session-delete"></a>`delete` · <a id="event_session-read"></a>`read` · <a id="event_session-update"></a>`update`

### event_subscription

Subscriptions that decide which events a client receives.

Standard meanings: <a id="event_subscription-create"></a>`create` · <a id="event_subscription-delete"></a>`delete` · <a id="event_subscription-read"></a>`read` · <a id="event_subscription-update"></a>`update`

## Cloud

### cloud_account

Connected cloud accounts, their verification state, and the fleet summaries drawn from them. See [Cloud accounts](/integrate/cloud/accounts/).

A service token cannot use this resource: every request is refused with `403` and the error code `cloud_principal_not_supported`. Use a personal API token or the console instead.

Standard meanings: <a id="cloud_account-create"></a>`create` · <a id="cloud_account-delete"></a>`delete` · <a id="cloud_account-read"></a>`read` · <a id="cloud_account-update"></a>`update`

| Action | What it permits |
|---|---|
| <a id="cloud_account-cloud_init_script"></a>`cloud_init_script` | Get the cloud-init script used to enroll instances |
| <a id="cloud_account-cloudformation_url"></a>`cloudformation_url` | Get the CloudFormation link for connecting the account |
| <a id="cloud_account-connection_guide"></a>`connection_guide` | Read the connection guide for the account |
| <a id="cloud_account-overview"></a>`overview` | Read an aggregate across every account you can see |
| <a id="cloud_account-recheck_remote_command"></a>`recheck_remote_command` | Re-check whether the account's role may run remote commands |
| <a id="cloud_account-reconnect"></a>`reconnect` | Reset a failed or stuck connection back to pending to reconnect it |
| <a id="cloud_account-regions"></a>`regions` | Read per-region instance counts |
| <a id="cloud_account-summary"></a>`summary` | Read instance counts for the account |
| <a id="cloud_account-sync"></a>`sync` | Start a discovery run for the account |
| <a id="cloud_account-verify"></a>`verify` | Re-verify the stored credentials |

### cloud_connection_method

The available ways to connect a cloud account. See [Connecting AWS](/integrate/cloud/connect-aws/).

Standard meanings: <a id="cloud_connection_method-read"></a>`read`

### cloud_instance

Cloud instances discovered in a connected account, and agent installation on them. See [Cloud instances](/use/servers/cloud-instances/).

A service token cannot use this resource: every request is refused with `403` and the error code `cloud_principal_not_supported`. Use a personal API token or the console instead.

Standard meanings: <a id="cloud_instance-read"></a>`read` · <a id="cloud_instance-update"></a>`update`

| Action | What it permits |
|---|---|
| <a id="cloud_instance-bulk_install"></a>`bulk_install` | Install the agent on several instances at once |
| <a id="cloud_instance-install"></a>`install` | Install the agent on the instance |
| <a id="cloud_instance-install_guide"></a>`install_guide` | Read the manual install guide for the instance |
| <a id="cloud_instance-regions"></a>`regions` | Read per-region instance counts |

### installation_job

Progress records for agent installations started from the cloud instance list. See [Installing the agent](/integrate/cloud/install-agent/).

A service token cannot use this resource: every request is refused with `403` and the error code `cloud_principal_not_supported`. Use a personal API token or the console instead.

Standard meanings: <a id="installation_job-read"></a>`read`

## IP management

### network

Managed networks in IP management. Offered on API tokens and service tokens only when the IP extension is enabled for the workspace; a role can hold it either way.

Standard meanings: <a id="network-create"></a>`create` · <a id="network-delete"></a>`delete` · <a id="network-read"></a>`read` · <a id="network-update"></a>`update`

### subnet

Subnets inside a managed network. Offered on API tokens and service tokens only when the IP extension is enabled for the workspace; a role can hold it either way.

Standard meanings: <a id="subnet-create"></a>`create` · <a id="subnet-delete"></a>`delete` · <a id="subnet-read"></a>`read` · <a id="subnet-update"></a>`update`

### pool

Address pools that a subnet hands out from. Offered on API tokens and service tokens only when the IP extension is enabled for the workspace; a role can hold it either way.

Standard meanings: <a id="pool-create"></a>`create` · <a id="pool-delete"></a>`delete` · <a id="pool-read"></a>`read` · <a id="pool-update"></a>`update`

### device

Devices tracked in IP management. Offered on API tokens and service tokens only when the IP extension is enabled for the workspace; a role can hold it either way.

Standard meanings: <a id="device-create"></a>`create` · <a id="device-delete"></a>`delete` · <a id="device-read"></a>`read` · <a id="device-update"></a>`update`

### dhcp_server

The DHCP service running on a managed server, including restarting and upgrading it. Narrowed by Server ACL. Offered on API tokens and service tokens only when the IP extension is enabled for the workspace; a role can hold it either way.

Standard meanings: <a id="dhcp_server-create"></a>`create` · <a id="dhcp_server-delete"></a>`delete` · <a id="dhcp_server-read"></a>`read` · <a id="dhcp_server-update"></a>`update`

| Action | What it permits |
|---|---|
| <a id="dhcp_server-restart"></a>`restart` | Restart the service on the server |
| <a id="dhcp_server-upgrade"></a>`upgrade` | Upgrade the service on the server |

### lease

Address leases that DHCP has handed out. Narrowed by Server ACL. Offered on API tokens and service tokens only when the IP extension is enabled for the workspace; a role can hold it either way.

Standard meanings: <a id="lease-create"></a>`create` · <a id="lease-read"></a>`read`

| Action | What it permits |
|---|---|
| <a id="lease-ignore"></a>`ignore` | Mark a lease as ignored |

### dhcp_session

DHCP exchange records between a client and the server. Narrowed by Server ACL. Offered on API tokens and service tokens only when the IP extension is enabled for the workspace; a role can hold it either way.

Standard meanings: <a id="dhcp_session-read"></a>`read`

## DNS

### zone

DNS zones. Offered on API tokens and service tokens only when the DNS extension is enabled for the workspace; a role can hold it either way.

Standard meanings: <a id="zone-create"></a>`create` · <a id="zone-delete"></a>`delete` · <a id="zone-read"></a>`read` · <a id="zone-update"></a>`update`

### record

DNS records inside a zone. Offered on API tokens and service tokens only when the DNS extension is enabled for the workspace; a role can hold it either way.

Standard meanings: <a id="record-create"></a>`create` · <a id="record-delete"></a>`delete` · <a id="record-read"></a>`read` · <a id="record-update"></a>`update`

### dns_view

DNS views that decide which zone a client resolves against. Offered on API tokens and service tokens only when the DNS extension is enabled for the workspace; a role can hold it either way.

Standard meanings: <a id="dns_view-create"></a>`create` · <a id="dns_view-delete"></a>`delete` · <a id="dns_view-read"></a>`read` · <a id="dns_view-update"></a>`update`

### dns_server

The DNS service running on a managed server, including restarting and upgrading it. Narrowed by Server ACL. Offered on API tokens and service tokens only when the DNS extension is enabled for the workspace; a role can hold it either way.

Standard meanings: <a id="dns_server-create"></a>`create` · <a id="dns_server-delete"></a>`delete` · <a id="dns_server-read"></a>`read` · <a id="dns_server-update"></a>`update`

| Action | What it permits |
|---|---|
| <a id="dns_server-restart"></a>`restart` | Restart the service on the server |
| <a id="dns_server-upgrade"></a>`upgrade` | Upgrade the service on the server |

## Proxy

### domain_group

Groups of domains referenced by proxy access rules. Offered on API tokens and service tokens only when the Proxy extension is enabled for the workspace; a role can hold it either way.

Standard meanings: <a id="domain_group-create"></a>`create` · <a id="domain_group-delete"></a>`delete` · <a id="domain_group-read"></a>`read` · <a id="domain_group-update"></a>`update`

### domain

Individual domains used in proxy access rules. Offered on API tokens and service tokens only when the Proxy extension is enabled for the workspace; a role can hold it either way.

Standard meanings: <a id="domain-create"></a>`create` · <a id="domain-delete"></a>`delete` · <a id="domain-read"></a>`read` · <a id="domain-update"></a>`update`

### access_policy

Proxy access policies: the named sets of rules a proxy profile applies. Offered on API tokens and service tokens only when the Proxy extension is enabled for the workspace; a role can hold it either way.

Standard meanings: <a id="access_policy-create"></a>`create` · <a id="access_policy-delete"></a>`delete` · <a id="access_policy-read"></a>`read` · <a id="access_policy-update"></a>`update`

### access_rule

Individual rules inside a proxy access policy. Offered on API tokens and service tokens only when the Proxy extension is enabled for the workspace; a role can hold it either way.

Standard meanings: <a id="access_rule-create"></a>`create` · <a id="access_rule-delete"></a>`delete` · <a id="access_rule-read"></a>`read` · <a id="access_rule-update"></a>`update`

### proxy_profile

Proxy profiles that bind an access policy to the servers running the proxy. Offered on API tokens and service tokens only when the Proxy extension is enabled for the workspace; a role can hold it either way.

Standard meanings: <a id="proxy_profile-create"></a>`create` · <a id="proxy_profile-delete"></a>`delete` · <a id="proxy_profile-read"></a>`read` · <a id="proxy_profile-update"></a>`update`

### proxy_server

The proxy service running on a managed server, including restarting and upgrading it. Narrowed by Server ACL. Offered on API tokens and service tokens only when the Proxy extension is enabled for the workspace; a role can hold it either way.

Standard meanings: <a id="proxy_server-create"></a>`create` · <a id="proxy_server-delete"></a>`delete` · <a id="proxy_server-read"></a>`read` · <a id="proxy_server-update"></a>`update`

| Action | What it permits |
|---|---|
| <a id="proxy_server-restart"></a>`restart` | Restart the service on the server |
| <a id="proxy_server-upgrade"></a>`upgrade` | Upgrade the service on the server |

## Private SSL

### authority

Internal certificate authorities, including the revocation list they publish. Narrowed by Server ACL. Offered on API tokens and service tokens only when the Private SSL extension is enabled for the workspace; a role can hold it either way. See [Certificate authorities](/use/private-ssl/authorities/).

Standard meanings: <a id="authority-create"></a>`create` · <a id="authority-delete"></a>`delete` · <a id="authority-read"></a>`read` · <a id="authority-update"></a>`update`

| Action | What it permits |
|---|---|
| <a id="authority-crl"></a>`crl` | Download the revocation list |
| <a id="authority-restart"></a>`restart` | Restart the service on the server |
| <a id="authority-upgrade"></a>`upgrade` | Upgrade the service on the server |

### sign_request

Certificate signing requests and their review outcome. Offered on API tokens and service tokens only when the Private SSL extension is enabled for the workspace; a role can hold it either way. See [Certificate requests](/use/private-ssl/requests/).

Standard meanings: <a id="sign_request-create"></a>`create` · <a id="sign_request-delete"></a>`delete` · <a id="sign_request-read"></a>`read` · <a id="sign_request-update"></a>`update`

| Action | What it permits |
|---|---|
| <a id="sign_request-approve"></a>`approve` | Approve the request |
| <a id="sign_request-deny"></a>`deny` | Deny the request |
| <a id="sign_request-mark_failed"></a>`mark_failed` | Mark the request as failed |
| <a id="sign_request-retry"></a>`retry` | Retry the request |
| <a id="sign_request-submit"></a>`submit` | Upload the CSR for a request still awaiting a decision |

### certificate

Issued certificates. Offered on API tokens and service tokens only when the Private SSL extension is enabled for the workspace; a role can hold it either way. See [Certificates](/use/private-ssl/certificates/).

Standard meanings: <a id="certificate-read"></a>`read`

| Action | What it permits |
|---|---|
| <a id="certificate-by_serial"></a>`by_serial` | Look up a certificate by serial number |

### revoke_request

Certificate revocation requests and their review outcome. Offered on API tokens and service tokens only when the Private SSL extension is enabled for the workspace; a role can hold it either way. See [Certificates](/use/private-ssl/certificates/).

Standard meanings: <a id="revoke_request-create"></a>`create` · <a id="revoke_request-delete"></a>`delete` · <a id="revoke_request-read"></a>`read` · <a id="revoke_request-update"></a>`update`

| Action | What it permits |
|---|---|
| <a id="revoke_request-approve"></a>`approve` | Approve the request |
| <a id="revoke_request-deny"></a>`deny` | Deny the request |
| <a id="revoke_request-mark_failed"></a>`mark_failed` | Mark the request as failed |
| <a id="revoke_request-retry"></a>`retry` | Retry the request |

## Packages

### package

Packages held in the workspace package mirror.

Standard meanings: <a id="package-create"></a>`create` · <a id="package-delete"></a>`delete` · <a id="package-read"></a>`read` · <a id="package-update"></a>`update`

### package_entry

Individual files inside a mirrored package.

Standard meanings: <a id="package_entry-create"></a>`create` · <a id="package_entry-delete"></a>`delete` · <a id="package_entry-read"></a>`read`

| Action | What it permits |
|---|---|
| <a id="package_entry-download"></a>`download` | Download the package file |

## Firewall

These resources belong to the Firewall extension. On a token they appear only while the extension is on.

### security_group

Security groups: sets of firewall rules you apply to servers, with snapshots to roll back to.

Standard meanings: <a id="security_group-create"></a>`create` · <a id="security_group-delete"></a>`delete` · <a id="security_group-read"></a>`read` · <a id="security_group-update"></a>`update`

| Action | What it permits |
|---|---|
| <a id="security_group-apply"></a>`apply` | Apply pending rule changes |
| <a id="security_group-capture"></a>`capture` | Capture a snapshot of the group now |
| <a id="security_group-preview"></a>`preview` | Preview what a rollback would change |
| <a id="security_group-rollback"></a>`rollback` | Roll the group back to a snapshot |
| <a id="security_group-snapshots"></a>`snapshots` | List the group's recent snapshots |

### security_group_assignment

Which security groups apply to a server, and in what order. Narrowed by Server ACL.

Standard meanings: <a id="security_group_assignment-create"></a>`create` · <a id="security_group_assignment-delete"></a>`delete` · <a id="security_group_assignment-read"></a>`read` · <a id="security_group_assignment-update"></a>`update`

| Action | What it permits |
|---|---|
| <a id="security_group_assignment-reorder"></a>`reorder` | Change the order of the groups on a server |

### security_group_snapshot

Point-in-time snapshots of a security group's configuration.

Standard meanings: <a id="security_group_snapshot-create"></a>`create` · <a id="security_group_snapshot-delete"></a>`delete` · <a id="security_group_snapshot-read"></a>`read`

| Action | What it permits |
|---|---|
| <a id="security_group_snapshot-preview"></a>`preview` | Preview what rolling back to this snapshot would change |
| <a id="security_group_snapshot-rollback"></a>`rollback` | Roll the group back to this snapshot |

### firewall_chain

Chains that organize the rules inside a security group.

Standard meanings: <a id="firewall_chain-create"></a>`create` · <a id="firewall_chain-delete"></a>`delete` · <a id="firewall_chain-read"></a>`read` · <a id="firewall_chain-update"></a>`update`

Deleting a chain deletes its rules too.

### firewall_rule

Firewall rules within a chain.

Standard meanings: <a id="firewall_rule-create"></a>`create` · <a id="firewall_rule-delete"></a>`delete` · <a id="firewall_rule-read"></a>`read` · <a id="firewall_rule-update"></a>`update`

| Action | What it permits |
|---|---|
| <a id="firewall_rule-reorder"></a>`reorder` | Change the order of rules within a chain |

## Monitoring and audit

### alert_rule

Alert rules that decide when a server raises an alert. Offered on API tokens and service tokens only when the Metrics extension is enabled for the workspace; a role can hold it either way. See [Server monitoring](/use/servers/monitor/).

Standard meanings: <a id="alert_rule-create"></a>`create` · <a id="alert_rule-delete"></a>`delete` · <a id="alert_rule-read"></a>`read` · <a id="alert_rule-update"></a>`update`

### rule_override

A server's departure from an alert rule: its own threshold, recovery threshold, or duration, or an exemption from the rule entirely. Narrowed by Server ACL—only for servers the credential can already manage. Offered on API tokens and service tokens only when the Metrics extension is enabled for the workspace; a role can hold it either way. See [Server monitoring](/use/servers/monitor/#metric-alerts).

Standard meanings: <a id="rule_override-create"></a>`create` · <a id="rule_override-delete"></a>`delete` · <a id="rule_override-read"></a>`read` · <a id="rule_override-update"></a>`update`

### metric

Resource usage metrics collected from servers. Narrowed by Server ACL. Offered on API tokens and service tokens only when the Metrics extension is enabled for the workspace; a role can hold it either way. See [Server monitoring](/use/servers/monitor/).

Standard meanings: <a id="metric-read"></a>`read`

| Action | What it permits |
|---|---|
| <a id="metric-top"></a>`top` | Read the highest-usage entries |

### alert

Alerts that servers have raised. Narrowed by Server ACL. See [Server monitoring](/use/servers/monitor/).

Standard meanings: <a id="alert-read"></a>`read`

| Action | What it permits |
|---|---|
| <a id="alert-acknowledge"></a>`acknowledge` | Acknowledge an alert |

### activity

The workspace activity log. See [Activity log](/use/audit/governance/activity-log/).

Standard meanings: <a id="activity-read"></a>`read`

Reading anyone's activity but your own needs `activity:read` held across the workspace. Without it, you read only your own records, and filtering by group is refused with `403`.

| Action | What it permits |
|---|---|
| <a id="activity-chart"></a>`chart` | Read activity as a time series |

### activity_report

The workspace's periodic activity reports and the review decisions recorded on their findings.

Standard meanings: <a id="activity_report-read"></a>`read`

| Action | What it permits |
|---|---|
| <a id="activity_report-dispose"></a>`dispose` | Record a review decision on a report's finding. Needs a person behind the credential: a service token is refused with `activity_report_principal_not_supported` |

### role_audit_log

The record of role grants and revocations. See [Audit](/use/audit/).

Standard meanings: <a id="role_audit_log-read"></a>`read`

## Access control lists

### command_acl

Command ACL entries: which commands a credential may run. See [Command patterns](/use/iam/applications/service-tokens/command-patterns/).

These scopes do not let a token manage ACLs. The [ACL API](/reference/api/acl/) refuses all personal API tokens and service tokens with `403 permission_denied`; sign in to the console or CLI to manage ACLs.

Standard meanings: <a id="command_acl-create"></a>`create` · <a id="command_acl-delete"></a>`delete` · <a id="command_acl-read"></a>`read` · <a id="command_acl-update"></a>`update`

| Action | What it permits |
|---|---|
| <a id="command_acl-bulk_create"></a>`bulk_create` | Create several entries in one request |
| <a id="command_acl-bulk_delete"></a>`bulk_delete` | Delete several entries in one request |
| <a id="command_acl-bulk_update"></a>`bulk_update` | Modify several entries in one request |

### server_acl

Server ACL entries: which servers a credential may reach. See [API access tokens](/use/settings/api-tokens/).

These scopes do not let a token manage ACLs. The [ACL API](/reference/api/acl/) refuses all personal API tokens and service tokens with `403 permission_denied`; sign in to the console or CLI to manage ACLs.

Standard meanings: <a id="server_acl-create"></a>`create` · <a id="server_acl-delete"></a>`delete` · <a id="server_acl-read"></a>`read` · <a id="server_acl-update"></a>`update`

| Action | What it permits |
|---|---|
| <a id="server_acl-bulk_create"></a>`bulk_create` | Create several entries in one request |
| <a id="server_acl-bulk_delete"></a>`bulk_delete` | Delete several entries in one request |

### file_acl

File ACL entries: which paths a credential may transfer. See [WebFTP permissions](/use/work-sessions/files/permissions/).

These scopes do not let a token manage ACLs. The [ACL API](/reference/api/acl/) refuses all personal API tokens and service tokens with `403 permission_denied`; sign in to the console or CLI to manage ACLs.

Standard meanings: <a id="file_acl-create"></a>`create` · <a id="file_acl-delete"></a>`delete` · <a id="file_acl-read"></a>`read` · <a id="file_acl-update"></a>`update`

| Action | What it permits |
|---|---|
| <a id="file_acl-bulk_create"></a>`bulk_create` | Create several entries in one request |
| <a id="file_acl-bulk_delete"></a>`bulk_delete` | Delete several entries in one request |
| <a id="file_acl-bulk_update"></a>`bulk_update` | Modify several entries in one request |

## Approvals and sudo

### approval_policy

Approval policies: what needs review, and who reviews it. See [Access rules](/use/approvals/#access-rules).

Standard meanings: <a id="approval_policy-create"></a>`create` · <a id="approval_policy-delete"></a>`delete` · <a id="approval_policy-read"></a>`read` · <a id="approval_policy-update"></a>`update`

### approval_request

Approval requests and the decision made on them. See [Approvals](/use/approvals/).

Standard meanings: <a id="approval_request-create"></a>`create` · <a id="approval_request-delete"></a>`delete` · <a id="approval_request-read"></a>`read`

| Action | What it permits |
|---|---|
| <a id="approval_request-approve"></a>`approve` | Approve the request |
| <a id="approval_request-cancel"></a>`cancel` | Cancel a request you made |
| <a id="approval_request-my_requests"></a>`my_requests` | List the requests you made |
| <a id="approval_request-preview_account_adjustment"></a>`preview_account_adjustment` | Preview the target account candidates for a work session before approving |
| <a id="approval_request-reject"></a>`reject` | Reject the request |

### sudo_policy

Sudo policies that decide when privilege elevation is allowed. See [Sudo with MFA](/use/work-sessions/terminal/sudo-with-mfa/).

Standard meanings: <a id="sudo_policy-create"></a>`create` · <a id="sudo_policy-delete"></a>`delete` · <a id="sudo_policy-read"></a>`read` · <a id="sudo_policy-update"></a>`update`

### sudo_policy_request

Requests to add or change a sudo policy. See [Sudo with MFA](/use/work-sessions/terminal/sudo-with-mfa/).

Standard meanings: <a id="sudo_policy_request-create"></a>`create` · <a id="sudo_policy_request-read"></a>`read`

### sudo_grant

Granted privilege elevations and their verification state. See [Privilege elevation](/use/audit/events/sudo/).

Standard meanings: <a id="sudo_grant-read"></a>`read`

| Action | What it permits |
|---|---|
| <a id="sudo_grant-verify"></a>`verify` | Confirm a grant after MFA is completed |

## Notifications

### webhook

Outbound webhooks for workspace events. See [Webhooks](/integrate/webhooks/).

Standard meanings: <a id="webhook-create"></a>`create` · <a id="webhook-delete"></a>`delete` · <a id="webhook-read"></a>`read` · <a id="webhook-update"></a>`update`

### notification

In-product notifications addressed to you. See [Notifications](/use/settings/notifications/).

Standard meanings: <a id="notification-read"></a>`read` · <a id="notification-update"></a>`update`

| Action | What it permits |
|---|---|
| <a id="notification-dismiss"></a>`dismiss` | Dismiss a notification |

### slack_installation

The Slack connection for the workspace. See [Slack](/integrate/slack/).

Standard meanings: <a id="slack_installation-delete"></a>`delete` · <a id="slack_installation-read"></a>`read` · <a id="slack_installation-update"></a>`update`

### slack_user_mapping

Pairings between Alpacon users and Slack members. See [Link members to Slack](/integrate/slack/#link-members-to-slack).

Standard meanings: <a id="slack_user_mapping-create"></a>`create` · <a id="slack_user_mapping-delete"></a>`delete` · <a id="slack_user_mapping-read"></a>`read`

| Action | What it permits |
|---|---|
| <a id="slack_user_mapping-candidates"></a>`candidates` | List Alpacon users that are not paired yet |
| <a id="slack_user_mapping-slack_members"></a>`slack_members` | List Slack members that are not paired yet |

## Workspace and IAM

### workspace

Workspace-level settings. See [Workspace settings](/use/workspace/settings/).

Standard meanings: <a id="workspace-read"></a>`read` · <a id="workspace-update"></a>`update`

### preferences

Workspace preferences, including which extensions are enabled. See [Workspace settings](/use/workspace/settings/).

Standard meanings: <a id="preferences-read"></a>`read` · <a id="preferences-update"></a>`update`

### user

Workspace user accounts. See [Users](/use/iam/users/).

Standard meanings: <a id="user-create"></a>`create` · <a id="user-delete"></a>`delete` · <a id="user-read"></a>`read` · <a id="user-update"></a>`update`

| Action | What it permits |
|---|---|
| <a id="user-remove_privileged"></a>`remove_privileged` | Remove or deactivate a privileged account; required in addition to the permission for the operation |

Service tokens cannot call the [users API](/reference/api/iam/users/).

### group

Groups used for grouping users and servers. See [Groups](/use/iam/groups/).

Standard meanings: <a id="group-create"></a>`create` · <a id="group-delete"></a>`delete` · <a id="group-read"></a>`read` · <a id="group-update"></a>`update`

### membership

Which users belong to which group, and with what group role. See [Assigning users to groups](/use/iam/groups/assign-users/).

Standard meanings: <a id="membership-read"></a>`read` · <a id="membership-update"></a>`update`

| Action | What it permits |
|---|---|
| <a id="membership-create"></a>`create` | Add a user to a group |
| <a id="membership-delete"></a>`delete` | Remove a user from a group |

### ai_agent

An AI agent represents an AI client, such as an MCP client or an AI coding agent using the CLI. You can track the client by name and see its credentials together.

| Action | What it permits |
|---|---|
| <a id="ai_agent-read"></a>`read` | List and view AI agents. Members always see their own agents; viewing other members' agents requires this permission workspace-wide or on specific agents |
| <a id="ai_agent-attach"></a>`attach` | Attach a service token to an agent, or move it to another agent. Cannot be granted to personal API tokens or service tokens |

The `admin`, `security_admin`, and `auditor` roles include `ai_agent:read` workspace-wide. Requests made with a token also require `ai_agent:read` in its scopes. Deleted agents and agents with no remaining credentials are excluded from both the list and detail views.

Attaching requires permission to create service tokens for the token's application (`service_token:create`). Attaching without an explicitly selected target also requires workspace-wide `ai_agent:attach`. When no target is selected, an already attached token stays with its current agent; an unattached token gets a new agent. You can select your own agent as the target. To select another member's agent, you need `ai_agent:attach` on that agent. To move a token, you must either own its current agent or have `ai_agent:attach` on that agent. The `admin` role includes `ai_agent:attach`; `security_admin` and `auditor` do not.

Personal API tokens and service tokens cannot include `ai_agent:attach`.

### application

Applications: the non-human identities that service tokens belong to. See [Applications](/use/iam/applications/).

Standard meanings: <a id="application-create"></a>`create` · <a id="application-delete"></a>`delete` · <a id="application-read"></a>`read` · <a id="application-update"></a>`update`

### service_token

Service tokens issued to an application, including rotation and emergency controls. See [Service tokens](/use/iam/applications/service-tokens/).

Standard meanings: <a id="service_token-read"></a>`read` · <a id="service_token-update"></a>`update`

| Action | What it permits |
|---|---|
| <a id="service_token-break_glass"></a>`break_glass` | Activate emergency access on the token |
| <a id="service_token-create"></a>`create` | Issue a service token |
| <a id="service_token-delete"></a>`delete` | Delete a service token |
| <a id="service_token-disable"></a>`disable` | Disable the token immediately |
| <a id="service_token-rotate"></a>`rotate` | Regenerate the token key |

## Troubleshooting

| Error code | What it means | What to do |
|---|---|---|
| `api_token_scope_exceeds_rbac` | A scope you selected is outside what your roles allow. | The response does not name the scope, so compare your selection against what `alpacon token scopes` lists for you and remove anything absent. |
| `service_token_scope_exceeds_role` | A scope is outside what the application's roles allow. | Grant the application the role that carries it, or drop the scope. |
| `api_token_acl_not_allowed` | The token holds the scope, but no ACL entry covers the server, command, or path you targeted. | Add the matching Server, Command, or File ACL entry for that token. |
| `auth_interactive_channel_requires_presence` | A token (personal API token, service token, or MCP connection) tried to open a terminal, a tunnel, or a WebFTP session. These need a person signed in, so no scope or ACL entry lifts the refusal. | Sign in with `alpacon login` without `-t` (add `--no-browser` on a machine without a browser), or use the console. For automation, run commands through the command API, and move files with `alpacon cp` under a token that holds the `file_upload` or `file_download` [preset](#presets). |
| `api_token_presets_not_allowed_on_update` | A preset was sent while editing an existing credential. | Send the individual scopes instead. Presets apply only at creation. |
| `No matching scopes for pattern` | A wildcard pattern covers no scope that exists. | Check the spelling of the resource or action against the catalog above. |
| `Unknown scope` | The scope name is not in the catalog. | Check the spelling, and note that resource names are singular (`server`, not `servers`). |

## Related

- [API tokens](/reference/api/tokens/)—the API for creating and editing tokens
- [`alpacon token scopes`](/reference/cli/token/scopes/)—list the scopes you can grant right now
- [API access tokens](/use/settings/api-tokens/)—issuing and managing a personal token
- [Service tokens](/use/iam/applications/service-tokens/)—issuing a token for an application
- [Permissions](/use/workspace/settings/roles/)—how roles grant these same entries to users and groups

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