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.

Warning

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

TermWhat it is
Scope (this page)A resource:action entry. Roles, API tokens, and service tokens all use it.
Work session scopeOne of websh, command, webftp, tunnel, editor, sudo: which kinds of activity an approved work session allows. Set with alpacon work-session create --scope.
Permission scopeIn role management, 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 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

FormExampleMeaning
resource:actionserver:readOne action on one resource
resource:*server:*Every action on one resource
*:action*:readOne 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.

ActionMeaning
createCreate a new one.
readList them, and read one in detail.
updateModify an existing one.
deleteDelete 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.

ResourceAction
serverread
sessioncreate · read · close · refresh
userchannelcreate · read · close
commandread · 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.

ResourceAction
serverread
commandcreate · read · chunks · purpose
event_sessioncreate · read
event_subscriptioncreate · read

Command history (command_read)

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

ResourceAction
serverread
commandread · chunks

File upload (file_upload)

Send files to servers with alpacon cp local server:.

ResourceAction
serverread
uploaded_filecreate · upload · status · bulk · bulk_upload · read

File download (file_download)

Fetch files from servers with alpacon cp server: local.

ResourceAction
serverread
downloaded_filecreate · download · status · bulk · read

File transfer (file_transfer)

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

ResourceAction
serverread
uploaded_filecreate · upload · status · bulk · bulk_upload · read
downloaded_filecreate · download · status · bulk · read
ftp_sessioncreate · 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.

ResourceAction
serverread
tunnel_sessioncreate · 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.

ResourceAction
serverread · collection_profile
metricread · top
alertread · acknowledge
alert_ruleread

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.

ResourceAction
authorityread
sign_requestread · create · submit
certificateread
revoke_requestread · create

Group management (group_management)

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

ResourceAction
groupread · create · update · delete
membershipread · 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.

ResourceAction
serverread · collection_profile
commandread
eventread
sessionread
userchannelread
tunnel_sessionread
ftp_sessionread
uploaded_fileread
downloaded_fileread
metricread
alertread
alert_ruleread

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 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, 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 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. A role keeps every scope in the preset.

A scope does not bypass console-only access. Changing approval policies (approval_policy:create, approval_policy:update, approval_policy:delete) and creating sudo policies (sudo_policy:create) require the console. 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

ResourceAreaActionsObject narrowing
serverServers25Server
noteServers4Server
registration_tokenServers3—
registration_methodServers2—
procServers5Server
backhaul_sessionServers1Server
sessionSessions and terminals13Server
session_analysisSessions and terminals2—
userchannelSessions and terminals5Server
tunnel_sessionSessions and terminals5Server
work_sessionSessions and terminals14Server
ftp_sessionFile transfer6Server
uploaded_fileFile transfer7Server, File
downloaded_fileFile transfer6Server, File
commandCommands and events5Server, Command
approved_file_executionCommands and events2—
eventCommands and events1Server
local_access_eventCommands and events1Server
local_access_findingCommands and events2Server
direct_access_entryCommands and events5—
local_access_detectionCommands and events1—
event_sessionCommands and events4—
event_subscriptionCommands and events4—
cloud_accountCloud14—
cloud_connection_methodCloud1—
cloud_instanceCloud6—
installation_jobCloud1—
networkIP management4—
subnetIP management4—
poolIP management4—
deviceIP management4—
dhcp_serverIP management6Server
leaseIP management3Server
dhcp_sessionIP management1Server
zoneDNS4—
recordDNS4—
dns_viewDNS4—
dns_serverDNS6Server
domain_groupProxy4—
domainProxy4—
access_policyProxy4—
access_ruleProxy4—
proxy_profileProxy4—
proxy_serverProxy6Server
authorityPrivate SSL7Server
sign_requestPrivate SSL9—
certificatePrivate SSL2—
revoke_requestPrivate SSL8—
packagePackages4—
package_entryPackages4—
security_groupFirewall9—
security_group_assignmentFirewall5Server
security_group_snapshotFirewall5—
firewall_chainFirewall4—
firewall_ruleFirewall5—
alert_ruleMonitoring and audit4—
rule_overrideMonitoring and audit4Server
metricMonitoring and audit2Server
alertMonitoring and audit2Server
activityMonitoring and audit2—
activity_reportMonitoring and audit2—
role_audit_logMonitoring and audit1—
command_aclAccess control lists7—
server_aclAccess control lists6—
file_aclAccess control lists7—
approval_policyApprovals and sudo4—
approval_requestApprovals and sudo8—
sudo_policyApprovals and sudo4—
sudo_policy_requestApprovals and sudo2—
sudo_grantApprovals and sudo2—
webhookNotifications4—
notificationNotifications3—
slack_installationNotifications3—
slack_user_mappingNotifications5—
workspaceWorkspace and IAM2—
preferencesWorkspace and IAM2—
userWorkspace and IAM5—
groupWorkspace and IAM4—
membershipWorkspace and IAM4—
applicationWorkspace and IAM4—
service_tokenWorkspace and IAM7—

Servers

server

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

Standard meanings: read · update

ActionWhat it permits
accessServer access
actionsRun a built-in server action
attach_ruleAttach an alert rule to the server
collection_profileRead the server’s collection profile—what it collects, how often, and what it doesn’t
createAdd a server to the workspace
deleteRemove a server from the workspace
detach_ruleDetach an alert rule from the server
groupsRead the server’s system groups
hexagonRead the fleet status overview
infoRead the server’s system information
interfacesRead the server’s network interfaces
muteMute or unmute the server’s alerts
osRead the server’s OS version
os_distributionRead OS distribution statistics across servers
packagesRead the packages installed on the server
registerLet a server enroll itself
reserved_commandsRead commands scheduled to run later
search_recordsRecord search
starRead and set the favorite marker
timeRead the server’s system time
usersRead the server’s system users

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

ActionWhat it permits
createCreate a registration token

registration_method

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

Standard meanings: read

ActionWhat it permits
guideGenerate 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.

Standard meanings: read

ActionWhat it permits
adoptLink a discovered system account to an Alpacon user
coverageRead account coverage per server and across the fleet
resolveSettle a discovered account that is waiting on a decision
unadoptUnlink a system account from its Alpacon user

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

ActionWhat it permits
analysisRead the AI analysis of a session
analyzeStart AI analysis of a session
closeClose a session
createOpen a Websh terminal session
force_closeClose a session that belongs to someone else
inviteInvite people to the session by email
recordsRead the session transcript
refreshRedraw the terminal of an open session
search_recordsSearch within the session transcript
shareCreate a share link for the session

session_analysis

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

Standard meanings: read

ActionWhat it permits
aggregateRead 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.

Standard meanings: delete · read · update

ActionWhat it permits
closeClose a viewer connection
createJoin a terminal session

tunnel_session

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

Standard meanings: read

ActionWhat it permits
closeClose a session
createOpen a tunnel session
force_closeClose a session that belongs to someone else
reconnectReconnect 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.

The work-session API 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: read · update

ActionWhat it permits
activateMove an approved session to active
analyzeStart AI analysis of a session
approveApprove the session’s request in the web console only; unavailable to tokens
candidate_target_accountsList candidate accounts on the named servers (also requires proc:read)
completeComplete a running session
createRequest a work session
extendExtend a running session’s expiry
rejectReject the session’s request in the web console only; unavailable to tokens
resolve_target_accountCheck one candidate account before creating a session (also requires proc:read)
revokeForce-terminate a session; a token’s owner must be a Superuser
suggest_scopesGet recommended scope presets before creating a session
timelineRead the session timeline

File transfer

ftp_session

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

Standard meanings: delete · read · update

ActionWhat it permits
closeClose a session
createOpen a WebFTP session
force_closeClose 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.

Standard meanings: read

ActionWhat it permits
bulkCreate several transfers in one request
bulk_uploadStart several transfers in one request
createStart sending a file to a server
downloadDownload the transferred file
statusRead the transfer status
uploadStart 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.

Standard meanings: read

ActionWhat it permits
bulkCreate several transfers in one request
createStart fetching a file from a server
downloadDownload the fetched file
statusRead the transfer status
uploadReceive 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.

ActionWhat it permits
chunksRead command output in chunks
createRun a command on a server
deleteDelete a command record
purposeState why a held command is being run, so it is judged again
readRead 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: read

ActionWhat it permits
revokeStop a grant from admitting further runs

event

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

Standard meanings: read

local_access_event

A signed-in person with this read permission at workspace scope can read all these records; a personal API token also needs the corresponding scope, while a service token needs the scope and is limited by Server ACL.

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

A signed-in person with this read permission at workspace scope can read all these records; a personal API token also needs the corresponding scope, while a service token needs the scope and is limited by Server ACL.

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

ActionWhat it permits
disposeRecord 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. 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

ActionWhat it permits
requestAsk a policy owner for a standing entry

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.

ActionWhat it permits
updateTurn direct-login detection on or off

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.

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

ActionWhat it permits
cloud_init_scriptGet the cloud-init script used to enroll instances
cloudformation_urlGet the CloudFormation link for connecting the account
connection_guideRead the connection guide for the account
overviewRead an aggregate across every account you can see
recheck_remote_commandRe-check whether the account’s role may run remote commands
reconnectReset a failed or stuck connection back to pending to reconnect it
regionsRead per-region instance counts
summaryRead instance counts for the account
syncStart a discovery run for the account
verifyRe-verify the stored credentials

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.

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

ActionWhat it permits
bulk_installInstall the agent on several instances at once
installInstall the agent on the instance
install_guideRead the manual install guide for the instance
regionsRead per-region instance counts

installation_job

Progress records for agent installations started from the cloud instance list. See Installing the 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: 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: create · delete · read · 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: create · delete · read · 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: create · delete · read · 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: create · delete · read · 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: create · delete · read · update

ActionWhat it permits
restartRestart the service on the server
upgradeUpgrade 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: create · read

ActionWhat it permits
ignoreMark 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: 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

ActionWhat it permits
restartRestart the service on the server
upgradeUpgrade 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: 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

ActionWhat it permits
restartRestart the service on the server
upgradeUpgrade 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.

Standard meanings: create · delete · read · update

ActionWhat it permits
crlDownload the revocation list
restartRestart the service on the server
upgradeUpgrade 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.

Standard meanings: create · delete · read · update

ActionWhat it permits
approveApprove the request
denyDeny the request
mark_failedMark the request as failed
retryRetry the request
submitUpload 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.

Standard meanings: read

ActionWhat it permits
by_serialLook 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.

Standard meanings: create · delete · read · update

ActionWhat it permits
approveApprove the request
denyDeny the request
mark_failedMark the request as failed
retryRetry the request

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

ActionWhat it permits
downloadDownload 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: create · delete · read · update

ActionWhat it permits
applyApply pending rule changes
captureCapture a snapshot of the group now
previewPreview what a rollback would change
rollbackRoll the group back to a snapshot
snapshotsList 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: create · delete · read · update

ActionWhat it permits
reorderChange the order of the groups on a server

security_group_snapshot

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

Standard meanings: create · delete · read

ActionWhat it permits
previewPreview what rolling back to this snapshot would change
rollbackRoll the group back to this snapshot

firewall_chain

Chains that organize the rules inside a security group.

Standard meanings: create · delete · read · update

Deleting a chain deletes its rules too.

firewall_rule

Firewall rules within a chain.

Standard meanings: create · delete · read · update

ActionWhat it permits
reorderChange 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.

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

ActionWhat it permits
topRead the highest-usage entries

alert

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

Standard meanings: read

ActionWhat it permits
acknowledgeAcknowledge an alert

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.

ActionWhat it permits
chartRead activity as a time series

activity_report

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

Standard meanings: read

ActionWhat it permits
disposeRecord 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.

Standard meanings: read

Access control lists

command_acl

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

These scopes do not let a token manage ACLs. The ACL API refuses all personal API tokens and service tokens with 403 permission_denied; sign in to the console or CLI to manage ACLs.

Standard meanings: create · delete · read · update

ActionWhat it permits
bulk_createCreate several entries in one request
bulk_deleteDelete several entries in one request
bulk_updateModify several entries in one request

server_acl

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

These scopes do not let a token manage ACLs. The ACL API refuses all personal API tokens and service tokens with 403 permission_denied; sign in to the console or CLI to manage ACLs.

Standard meanings: create · delete · read · update

ActionWhat it permits
bulk_createCreate several entries in one request
bulk_deleteDelete several entries in one request

file_acl

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

These scopes do not let a token manage ACLs. The ACL API refuses all personal API tokens and service tokens with 403 permission_denied; sign in to the console or CLI to manage ACLs.

Standard meanings: create · delete · read · update

ActionWhat it permits
bulk_createCreate several entries in one request
bulk_deleteDelete several entries in one request
bulk_updateModify several entries in one request

Approvals and sudo

approval_policy

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

Standard meanings: create · delete · read · update

approval_request

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

Standard meanings: create · delete · read

ActionWhat it permits
approveApprove the request
cancelCancel a request you made
my_requestsList the requests you made
preview_account_adjustmentPreview the target account candidates for a work session before approving
rejectReject the request

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 Privilege elevation.

Standard meanings: read

ActionWhat it permits
verifyConfirm a grant after MFA is completed

Notifications

webhook

Outbound webhooks for workspace events. See Webhooks.

Standard meanings: create · delete · read · update

notification

In-product notifications addressed to you. See Notifications.

Standard meanings: read · update

ActionWhat it permits
dismissDismiss a notification

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

ActionWhat it permits
candidatesList Alpacon users that are not paired yet
slack_membersList Slack members that are not paired yet

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

ActionWhat it permits
remove_privilegedRemove or deactivate a privileged account; required in addition to the permission for the operation

Service tokens cannot call the users API.

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

ActionWhat it permits
createAdd a user to a group
deleteRemove a user from a group

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

ActionWhat it permits
break_glassActivate emergency access on the token
createIssue a service token
deleteDelete a service token
disableDisable the token immediately
rotateRegenerate the token key

Troubleshooting

Error codeWhat it meansWhat to do
api_token_scope_exceeds_rbacA 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_roleA 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_allowedThe 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_presenceA 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.
api_token_presets_not_allowed_on_updateA preset was sent while editing an existing credential.Send the individual scopes instead. Presets apply only at creation.
No matching scopes for patternA wildcard pattern covers no scope that exists.Check the spelling of the resource or action against the catalog above.
Unknown scopeThe scope name is not in the catalog.Check the spelling, and note that resource names are singular (server, not servers).
Last updated: