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.

Terminal access (terminal_access)

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

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.

Tunnel session (tunnel_connect)

Open tunnel sessions to servers with alpacon tunnel.

Monitoring (monitoring)

Read server resource usage, and view and acknowledge alerts. Alert rules are readable but not editable.

Certificate management (cert_management)

Request and track certificates from the internal certificate authority.

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.

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. Resources belonging to DNS, Proxy, and Private SSL appear only when that extension is turned on, because a scope on them could never grant anything otherwise.

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.

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

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 Event audit.

Standard meanings: read

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

Firewall and security groups

firewall_rule

Individual firewall rules inside a chain, including their order. See Security groups.

Standard meanings: create · delete · read · update

firewall_chain

Rule chains that group firewall rules. See Security groups.

Standard meanings: create · delete · read · update

security_group

Security groups: the reusable rule sets you apply to servers, plus their snapshots and rollback. See Security groups.

Standard meanings: create · delete · read · update

security_group_assignment

Which security groups are attached to a server, and in what order. Narrowed by Server ACL. See Security groups.

Standard meanings: create · delete · read · update

security_group_snapshot

Saved snapshots of a security group, used to preview and roll back changes. See Security groups.

Standard meanings: create · delete · 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. Available only when the DNS extension is enabled for the workspace.

Standard meanings: create · delete · read · update

record

DNS records inside a zone. Available only when the DNS extension is enabled for the workspace.

Standard meanings: create · delete · read · update

dns_view

DNS views that decide which zone a client resolves against. Available only when the DNS extension is enabled for the workspace.

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. Available only when the DNS extension is enabled for the workspace.

Standard meanings: create · delete · read · update

Proxy

domain_group

Groups of domains referenced by proxy access rules. Available only when the Proxy extension is enabled for the workspace.

Standard meanings: create · delete · read · update

domain

Individual domains used in proxy access rules. Available only when the Proxy extension is enabled for the workspace.

Standard meanings: create · delete · read · update

access_policy

Proxy access policies: the named sets of rules a proxy profile applies. Available only when the Proxy extension is enabled for the workspace.

Standard meanings: create · delete · read · update

access_rule

Individual rules inside a proxy access policy. Available only when the Proxy extension is enabled for the workspace.

Standard meanings: create · delete · read · update

proxy_profile

Proxy profiles that bind an access policy to the servers running the proxy. Available only when the Proxy extension is enabled for the workspace.

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. Available only when the Proxy extension is enabled for the workspace.

Standard meanings: create · delete · read · update

Private SSL

authority

Internal certificate authorities, including the revocation list they publish. Narrowed by Server ACL. Available only when the Private SSL extension is enabled for the workspace. See Certificate authorities.

Standard meanings: create · delete · read · update

sign_request

Certificate signing requests and their review outcome. Available only when the Private SSL extension is enabled for the workspace. See Certificate requests.

Standard meanings: create · delete · read · update

certificate

Issued certificates. Available only when the Private SSL extension is enabled for the workspace. See Certificates.

Standard meanings: read

revoke_request

Certificate revocation requests and their review outcome. Available only when the Private SSL extension is enabled for the workspace. 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. See Server monitoring.

Standard meanings: create · delete · read · update

metric

Resource usage metrics collected from servers. Narrowed by Server ACL. 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

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