Access control & approvals tools
These tools manage the permission layer that decides what an API or service token is allowed to do, and the approval workflow for actions that need a human decision before they proceed. They back requests like “can this token run docker commands on web-01?”, “which servers does the CI token have access to?”, or “what’s still waiting for approval?”
Command, server, and file ACL rules are the prerequisite for the tools in Command execution and file transfer—a token with no matching ACL rule is denied even if it is otherwise valid. Approval requests and sudo policies cover a separate concern: actions that require elevated privilege or human sign-off, most often surfaced as a pending-approval result from Command execution or a Work Session in Work Sessions.
All tools accept workspace (required) and region (optional, defaults to the configured region). These common parameters are omitted from the tables below.
Summary
| Tool | Description | Access |
|---|---|---|
list_command_acls | List command ACL rules | Read-only |
create_command_acl | Create a command ACL rule | Additive |
update_command_acl | Update a command ACL rule | Idempotent write |
delete_command_acl | Delete a command ACL rule | Destructive |
list_server_acls | List server ACL rules | Read-only |
create_server_acl | Create a server ACL rule | Additive |
update_server_acl | Update a server ACL rule | Idempotent write |
delete_server_acl | Delete a server ACL rule | Destructive |
bulk_server_acl | Add or remove server ACL entries for multiple servers at once | Destructive |
list_file_acls | List file ACL rules | Read-only |
create_file_acl | Create a file ACL rule | Additive |
update_file_acl | Update a file ACL rule | Idempotent write |
delete_file_acl | Delete a file ACL rule | Destructive |
list_approval_requests | List pending and historical approval requests | Read-only |
get_approval_request | Get details of a specific approval request | Read-only |
explain_approval_decision | Explain that approving or rejecting a request is human-only | Read-only |
list_sudo_policies | List sudo policies | Read-only |
request_sudo_policy | Request a sudo policy for admin approval | Additive |
Command ACLs
Command ACL rules control which shell command patterns a token may run through execute_command. Each rule binds to exactly one token (an API token or a service token, never both) and can optionally be restricted to a system username or group.
list_command_acls
Lists command ACL rules configured in the workspace. Filter by api_token_id or service_token_id to see the rules for a specific token—providing both returns an error. Use this to check command execution permissions or debug a 403 error from execute_command.
Access: Read-only
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
api_token_id | string | No | Filter by API token ID (mutually exclusive with service_token_id) |
service_token_id | string | No | Filter by service token ID (mutually exclusive with api_token_id) |
page | integer | No | Page number for pagination |
page_size | integer | No | Number of items per page |
Example
“Why is the CI token getting denied when it runs
docker ps?”
The agent calls list_command_acls with api_token_id set to the CI token’s ID and checks whether a rule matching docker * (or docker ps exactly) exists.
create_command_acl
Creates a command ACL rule allowing a token to run commands matching a pattern, such as docker * or ls -la. Exactly one of api_token_id or service_token_id must be provided—the rule binds to that token.
Access: Additive
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
command | string | Yes | Command pattern to allow, e.g. docker *, ls -la. Supports * wildcards |
api_token_id | string | No* | API token this rule applies to (mutually exclusive with service_token_id; exactly one is required) |
service_token_id | string | No* | Service token this rule applies to (mutually exclusive with api_token_id; exactly one is required) |
username | string | No | System username restriction. Empty (default) restricts to the token owner only; * allows any user |
groupname | string | No | System groupname restriction. Empty (default) applies no restriction |
Example
“Let the deploy token run any
dockercommand on servers it has access to”
The agent calls create_command_acl with command="docker *" and api_token_id set to the deploy token’s ID.
update_command_acl
Updates an existing command ACL rule’s command pattern or username/groupname restriction. At least one field must change. The rule’s token binding cannot be changed here—delete and recreate the rule to rebind it to a different token.
Access: Idempotent write
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
acl_id | string | Yes | Command ACL rule ID to update |
command | string | No | New command pattern to allow |
username | string | No | System username restriction. Pass '' explicitly to clear an existing restriction; omit to leave unchanged |
groupname | string | No | System groupname restriction. Pass '' explicitly to clear an existing restriction; omit to leave unchanged |
Example
“Widen that command ACL rule to allow all
dockersubcommands, not justdocker ps”
The agent finds the rule with list_command_acls, then calls update_command_acl with the rule’s acl_id and command="docker *".
delete_command_acl
Permanently deletes a command ACL rule. This cannot be undone—the token immediately loses the permission the rule granted.
Access: Destructive
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
acl_id | string | Yes | Command ACL rule ID to delete |
Example
“Revoke the CI token’s ability to run
rmcommands”
The agent finds the matching rule with list_command_acls, confirms with the user, then calls delete_command_acl with that rule’s acl_id.
Server ACLs
Server ACL rules control which servers a token can access at all—the prerequisite for running commands or transferring files on that server, regardless of what command ACL or file ACL rules exist.
list_server_acls
Lists server ACL rules configured in the workspace. Filter by api_token_id or service_token_id to see which servers a specific token can reach—providing both returns an error.
Access: Read-only
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
api_token_id | string | No | Filter by API token ID (mutually exclusive with service_token_id) |
service_token_id | string | No | Filter by service token ID (mutually exclusive with api_token_id) |
page | integer | No | Page number for pagination |
page_size | integer | No | Number of items per page |
Example
“Which servers can the monitoring token reach?”
The agent calls list_server_acls with api_token_id set to the monitoring token’s ID and lists the servers returned.
create_server_acl
Creates a server ACL rule granting a token access to one specific server. Exactly one of api_token_id or service_token_id must be provided. To grant access to many servers in one call, use bulk_server_acl instead.
Access: Additive
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
server_id | string | Yes | Server UUID to grant access to |
api_token_id | string | No* | API token to grant access (mutually exclusive with service_token_id; exactly one is required) |
service_token_id | string | No* | Service token to grant access (mutually exclusive with api_token_id; exactly one is required) |
Example
“Give the deploy token access to web-01”
The agent calls create_server_acl with server_id set to web-01’s UUID and api_token_id set to the deploy token’s ID.
update_server_acl
Updates an existing server ACL rule. Unlike command and file ACL rules, a server ACL rule’s token binding can be changed here: providing api_token_id rebinds the rule to that API token (clearing any service token binding), and providing service_token_id does the reverse.
Access: Idempotent write
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
acl_id | string | Yes | Server ACL rule ID to update |
server_id | string | No | New server UUID |
api_token_id | string | No | New API token to rebind this rule to (mutually exclusive with service_token_id) |
service_token_id | string | No | New service token to rebind this rule to (mutually exclusive with api_token_id) |
Example
“Move that server ACL rule from the old CI token to the new one”
The agent calls update_server_acl with the rule’s acl_id and api_token_id set to the new token’s ID.
delete_server_acl
Permanently deletes a server ACL rule. This cannot be undone—the token immediately loses access to that server.
Access: Destructive
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
acl_id | string | Yes | Server ACL rule ID to delete |
Example
“Remove the contractor token’s access to db-01”
The agent finds the matching rule with list_server_acls, confirms with the user, then calls delete_server_acl with that rule’s acl_id.
bulk_server_acl
Adds or removes server ACL entries for up to 100 servers in a single call—the bulk equivalent of repeated create_server_acl or delete_server_acl calls. Exactly one of api_token_id or service_token_id must be provided.
This tool is always classified Destructive, even for action="add"—the classification is fixed for the tool as a whole, and the removal path is the more consequential one. Treat every call with the same care you would give a delete.
Access: Destructive
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
action | string | Yes | Bulk action: add (grant access) or remove (revoke access) |
server_ids | array | Yes | Server UUIDs to add or remove access for (1–100 items) |
api_token_id | string | No* | API token to operate on (mutually exclusive with service_token_id; exactly one is required) |
service_token_id | string | No* | Service token to operate on (mutually exclusive with api_token_id; exactly one is required) |
Example
“Give the monitoring token access to every server in the staging fleet”
The agent calls bulk_server_acl with action="add", server_ids set to the staging fleet’s UUIDs, and api_token_id set to the monitoring token’s ID.
File ACLs
File ACL rules control which file paths a token can upload to or download from over WebFTP. Each rule binds to exactly one token and can restrict the action to upload, download, or both.
list_file_acls
Lists file ACL rules configured in the workspace. Filter by api_token_id or service_token_id to see the rules for a specific token—providing both returns an error.
Access: Read-only
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
api_token_id | string | No | Filter by API token ID (mutually exclusive with service_token_id) |
service_token_id | string | No | Filter by service token ID (mutually exclusive with api_token_id) |
page | integer | No | Page number for pagination |
page_size | integer | No | Number of items per page |
Example
“Can the backup service token download from
/var/log?”
The agent calls list_file_acls with service_token_id set to the backup token’s ID and checks whether a matching rule allows download on that path.
create_file_acl
Creates a file ACL rule controlling upload or download access to a path pattern, such as /etc/nginx/* or /var/log/*.log. Exactly one of api_token_id or service_token_id must be provided.
Access: Additive
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
path | string | Yes | File path pattern to match, e.g. /etc/nginx/*, /var/log/*.log. Supports * wildcards |
action | string | Yes | Allowed action: upload, download, or * (both) |
api_token_id | string | No* | API token this rule applies to (mutually exclusive with service_token_id; exactly one is required) |
service_token_id | string | No* | Service token this rule applies to (mutually exclusive with api_token_id; exactly one is required) |
username | string | No | System username restriction. Empty (default) restricts to the token owner only; * allows any user |
groupname | string | No | System groupname restriction. Empty (default) applies no restriction |
Example
“Let the backup service token download anything under
/var/log”
The agent calls create_file_acl with path="/var/log/*", action="download", and service_token_id set to the backup token’s ID.
update_file_acl
Updates an existing file ACL rule’s path, action, or username/groupname restriction. The rule’s token binding cannot be changed here—delete and recreate the rule to rebind it to a different token.
Access: Idempotent write
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
acl_id | string | Yes | File ACL rule ID to update |
path | string | No | New file path pattern |
action | string | No | New allowed action: upload, download, or * |
username | string | No | System username restriction. Pass '' explicitly to clear an existing restriction; omit to leave unchanged |
groupname | string | No | System groupname restriction. Pass '' explicitly to clear an existing restriction; omit to leave unchanged |
Example
“Also let that token upload to
/etc/nginx, not just download”
The agent finds the rule with list_file_acls, then calls update_file_acl with the rule’s acl_id and action="*".
delete_file_acl
Permanently deletes a file ACL rule. This cannot be undone—the token immediately loses the file access the rule granted.
Access: Destructive
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
acl_id | string | Yes | File ACL rule ID to delete |
Example
“Revoke the contractor token’s ability to upload to
/etc”
The agent finds the matching rule with list_file_acls, confirms with the user, then calls delete_file_acl with that rule’s acl_id.
Approval requests
Approval requests appear when an action needs human sign-off before it proceeds—for example a sudo command blocked by a Work Session’s sudo policy, or a Work Session that is pending approval before it becomes active. These tools let an agent observe approval requests and explain the process, but not decide them.
There is no approve_request or reject_request tool, by design. Approving or rejecting a request is always a human decision made in the Alpacon web console (or Slack, if configured)—never through MCP, and never by the AI agent itself. Use list_approval_requests and get_approval_request to observe pending requests, and explain_approval_decision to get guidance for handing one off to a human.
list_approval_requests
Lists pending and historical approval requests in the workspace, with request type, status, and requester. Use this to review what’s waiting for a decision or check approval history.
Access: Read-only
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
status | string | No | Filter by status: pending, approved, rejected, cancelled, or expired |
page | integer | No | Page number for pagination |
page_size | integer | No | Number of items per page |
Example
“What’s still waiting for approval in this workspace?”
The agent calls list_approval_requests with status="pending" and summarizes the results for the user.
get_approval_request
Gets full detail for a single approval request: requester, request type, reason, status, and timestamps.
Access: Read-only
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
request_id | string | Yes | Approval request ID to retrieve |
Example
“Who requested approval request
a1b2c3d4and why?”
The agent calls get_approval_request with request_id="a1b2c3d4" and reports the requester and reason back to the user.
explain_approval_decision
Explains that approving or rejecting a request is a human-only, out-of-band action. This tool performs no mutation and contacts no Alpacon API endpoint—an AI agent must never be the approver. It returns structured guidance so the agent surfaces the request to a human and waits, instead of attempting to self-approve. Call it after list_approval_requests or get_approval_request, or right after a tool call returns a pending-approval result (for example a SUDO_APPROVAL_REQUIRED denial from execute_command, or a Work Session that lands pending).
Access: Read-only
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
request_id | string | No | Approval request ID this guidance refers to |
Example
“My command was denied because it needs sudo approval—what do I do?”
The agent calls explain_approval_decision and relays the guidance: surface the pending request to a human, who reviews and decides in the Alpacon web console, then retry the command once it’s approved.
Sudo policies
Sudo policies define which commands can run with elevated privileges, by which users, on which servers, and for how long. A command blocked by sudo policy during execute_command surfaces as a pending-approval result rather than a plain denial.
list_sudo_policies
Lists sudo policies configured in the workspace: policy names, allowed commands, assigned users/servers, and validity periods. Use this to audit which sudo privileges are configured.
Access: Read-only
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
page | integer | No | Page number for pagination |
page_size | integer | No | Number of items per page |
user | string | No | Filter to policies covering this user |
server_id | string | No | Filter to policies covering this server |
Example
“What sudo policies apply to the production servers?”
The agent calls list_sudo_policies and reviews each policy’s servers and commands fields for matches.
request_sudo_policy
Requests a sudo policy allowing named commands on named servers—this creates an approval request, not a policy: an admin has to approve it in the Alpacon web console or Slack before the policy takes effect, and the call returns a pending-approval result. Leaving users empty scopes the policy to the requester alone once approved, not to the whole workspace, and a non-superuser can only name themselves there.
There’s no way to request a policy that bypasses MFA through this tool—the server refuses that combination outright. An MFA-bypass policy needs an enterprise plan and a Work Session a human sets up directly.
Access: Additive
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
servers | array | Yes | Server UUIDs the policy should cover |
commands | array | Yes | Command patterns to allow under sudo |
reason | string | Yes | Justification shown to the approver |
users | array | No | User UUIDs the policy should cover. Omitted scopes the approved policy to the requester alone |
valid_from | string | No | ISO 8601 start of the validity window |
valid_until | string | No | ISO 8601 end of the validity window |
Example
“Ask for permission to run
systemctl restart nginxwith sudo on the web fleet for this deploy”
The agent calls request_sudo_policy with servers set to the web fleet’s UUIDs, commands=["systemctl restart nginx"], and a reason describing the deploy. The result comes back pending—check on it with list_approval_requests or get_approval_request, and use explain_approval_decision for guidance on handing it to a human, since only a human can approve it.
- Command execution tools: run commands gated by these command ACL rules and sudo policies
- Work Sessions: the approval-gated session that command execution and file transfers run inside
- IAM & API tokens tools: manage the users, groups, and tokens that ACL rules and sudo policies reference