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.

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

• 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. In practice * is available only to a workspace superuser.

Standard actions

Most resources use the same four action names.

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.

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.

Command history (command_read)

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

File upload (file_upload)

Send files to servers with alpacon cp local server:.

File download (file_download)

Fetch files from servers with alpacon cp server: local.

File transfer (file_transfer)

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

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.

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.

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.

Group management (group_management)

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

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.

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 DNS, Proxy, Private SSL, 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.

• 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 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, 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.

A preset that contains one of these still works: the scope is left out and the rest is applied. So on a credential, Terminal access grants eight of its ten scopes, File transfer fourteen of its fifteen, and Tunnel session three of its five—enough to list and close tunnels, not to open one. The preset keeps all of its scopes when you use it for a role.

Tokens issued before this rule may still carry these scopes. They keep them, and nothing changes for them: the interactive ones were already refused at the moment of use, and server:register keeps working as it did, as long as your roles still grant it.

A credential that carries full access (*) is not affected either: a token issued with full access can still use server:register. The interactive actions refuse it all the same, as they refuse every token. If that matters for your workspace, issue tokens with the specific scopes they need rather than full access.

All resources

Servers

server

Server records: registration, fleet listing, per-server detail, and grouping. Narrowed by Server ACL. See Server management.

Standard meanings: read · update

note

Free-form notes attached to a server. Narrowed by Server ACL. See Managing a server.

Standard meanings: create · delete · read · update

registration_token

Registration tokens that let a new server enroll itself. See Server registration tokens.

Standard meanings: delete · read

registration_method

The registration methods offered when adding a server, and the generated setup guide. See Registering a server.

Standard meanings: read

proc

System accounts discovered on managed servers, and how they map to Alpacon users. Narrowed by Server ACL. See Account selection.

Standard meanings: read

backhaul_session

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

Standard meanings: read

Sessions and terminals

session

Websh terminal sessions: opening, sharing, closing, and reading the recorded transcript. Narrowed by Server ACL. See Websh sessions.

Standard meanings: delete · read · update

session_analysis

AI analysis results produced for terminal sessions. See Session analysis.

Standard meanings: read

userchannel

Individual viewer connections within a terminal session, including shared and invited ones. Narrowed by Server ACL. See Websh sessions.

Standard meanings: delete · read · update

tunnel_session

Tunnel sessions used by the editor and by port forwarding. Narrowed by Server ACL. See Editor sessions.

Standard meanings: read

work_session

Work sessions: the time-boxed, approved access window and everything decided inside it. Narrowed by Server ACL. See Work sessions.

Standard meanings: read · update

File transfer

ftp_session

WebFTP browsing sessions on a server. Narrowed by Server ACL. See WebFTP.

Standard meanings: delete · read · update

uploaded_file

Files sent to a server, whether through WebFTP or alpacon cp. Narrowed by Server, File ACL. See Uploading files.

Standard meanings: read

downloaded_file

Files fetched from a server, whether through WebFTP or alpacon cp. Narrowed by Server, File ACL. See Downloading files.

Standard meanings: read

Commands and events

command

Commands run on servers, and their output. Narrowed by Server, Command ACL. See Command events.

event

The event log that records what happened on a server. Narrowed by Server ACL. See Event audit.

Standard meanings: read

local_access_event

Access events recorded on a server that did not come through Alpacon. Narrowed by Server ACL. See External access.

Standard meanings: read

local_access_finding

Findings that group direct logins for review, with the period summary and the evidence export. Narrowed by Server ACL. See Review direct logins. Reading the summary, exporting evidence and recording a disposition need a person signed in to the console, so a token holding this scope can only list and read findings.

Standard meanings: read

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. 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: create · delete · read · update

local_access_detection

The workspace’s direct-login detection switch. See 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.

event_session

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

Standard meanings: create · delete · read · update

event_subscription

Subscriptions that decide which events a client receives.

Standard meanings: create · delete · read · update

Cloud

cloud_account

Connected cloud accounts, their verification state, and the fleet summaries drawn from them. See Cloud accounts.

Standard meanings: create · delete · read · update

cloud_connection_method

The available ways to connect a cloud account. See Connecting AWS.

Standard meanings: read

cloud_instance

Cloud instances discovered in a connected account, and agent installation on them. See Cloud instances.

Standard meanings: read · update

installation_job

Progress records for agent installations started from the cloud instance list. See Installing the agent.

Standard meanings: read

IP management

network

Managed networks in IP management.

Standard meanings: create · delete · read · update

subnet

Subnets inside a managed network.

Standard meanings: create · delete · read · update

pool

Address pools that a subnet hands out from.

Standard meanings: create · delete · read · update

device

Devices tracked in IP management.

Standard meanings: create · delete · read · update

dhcp_server

The DHCP service running on a managed server, including restarting and upgrading it. Narrowed by Server ACL.

Standard meanings: create · delete · read · update

lease

Address leases that DHCP has handed out. Narrowed by Server ACL.

Standard meanings: create · read

dhcp_session

DHCP exchange records between a client and the server. Narrowed by Server ACL.

Standard meanings: 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: create · delete · read · 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: create · delete · read · 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: create · delete · read · 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: create · delete · read · update

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: create · delete · read · 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: create · delete · read · 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: create · delete · read · 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: create · delete · read · 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: create · delete · read · 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: create · delete · read · update

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.

Standard meanings: create · delete · read · update

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.

Standard meanings: create · delete · read · update

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.

Standard meanings: read

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.

Standard meanings: create · delete · read

Packages

package

Packages held in the workspace package mirror.

Standard meanings: create · delete · read · update

package_entry

Individual files inside a mirrored package.

Standard meanings: create · delete · read

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.

Standard meanings: create · delete · read · 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.

Standard meanings: create · delete · read · 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.

Standard meanings: read

alert

Alerts that servers have raised. Narrowed by Server ACL. See Server monitoring.

Standard meanings: read

activity

The workspace activity log. See Activity log.

Standard meanings: 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.

role_audit_log

The record of role grants and revocations. See Audit.

Standard meanings: read

Access control lists

command_acl

Command ACL entries: which commands a credential may run. See Command patterns.

Standard meanings: create · delete · read · update

server_acl

Server ACL entries: which servers a credential may reach. See API access tokens.

Standard meanings: create · delete · read · update

file_acl

File ACL entries: which paths a credential may transfer. See WebFTP permissions.

Standard meanings: create · delete · read · update

Approvals and sudo

approval_policy

Approval policies: what needs review, and who reviews it. See Approval governance.

Standard meanings: create · delete · read · update

approval_request

Approval requests and the decision made on them. See Approvals.

Standard meanings: create · delete · read

sudo_policy

Sudo policies that decide when privilege elevation is allowed. See Sudo with MFA.

Standard meanings: create · delete · read · update

sudo_policy_request

Requests to add or change a sudo policy. See Sudo with MFA.

Standard meanings: create · read

sudo_grant

Granted privilege elevations and their verification state. See Sudo events.

Standard meanings: read

Notifications

webhook

Outbound webhooks for workspace events. See Notifications.

Standard meanings: create · delete · read · update

notification

In-product notifications addressed to you. See Notifications.

Standard meanings: read · update

slack_installation

The Slack connection for the workspace. See Notifications.

Standard meanings: delete · read · update

slack_user_mapping

Pairings between Alpacon users and Slack members. See Notifications.

Standard meanings: create · delete · read

Workspace and IAM

workspace

Workspace-level settings. See Workspace settings.

Standard meanings: read · update

preferences

Workspace preferences, including which extensions are enabled. See Workspace settings.

Standard meanings: read · update

user

Workspace user accounts. See Users.

Standard meanings: create · delete · read · update

group

Groups used for grouping users and servers. See Groups.

Standard meanings: create · delete · read · update

membership

Which users belong to which group, and with what group role. See Assigning users to groups.

Standard meanings: read · update

application

Applications: the non-human identities that service tokens belong to. See Applications.

Standard meanings: create · delete · read · update

service_token

Service tokens issued to an application, including rotation and emergency controls. See Service tokens.

Standard meanings: read · update

Troubleshooting

Related

• API tokens—the API for creating and editing tokens
• alpacon token scopes—list the scopes you can grant right now
• API access tokens—issuing and managing a personal token
• Service tokens—issuing a token for an application
• Permissions—how roles grant these same entries to users and groups