API access token
API access tokens allow programmatic access to the Alpacon API for CI/CD pipelines, automation scripts, and other integrations. Each token can be restricted with scopes to control which resources and actions are permitted, and ACL rules to further limit commands, file operations, and server access.
Since these tokens allow access to the Alpacon API without an interactive login or password, never share them externally.
Token list
You can check Name, Scope count, Valid through, and Last update for each token.
Create token
- Click the Add button.
- Set the token Name.
- Set Expiration (7 days, 30 days, 60 days, 90 days, 1 year, custom, or no expiration).
- Select Scopes to define which resources and actions the token can access.
- Click Create.
- The generated token key is displayed on the detail screen. Copy and store it in a safe location—it cannot be retrieved after leaving the page.
Scopes
Scopes define which resources and actions an API access token can perform. The format is {resource}:{action}.
Available resources
Resources are grouped by category. Select a resource in the scope selection UI to see its available actions.
| Category | Resources |
|---|---|
| Servers | server, server_acl |
| Sessions | session, ftp_session, tunnel_session, backhaul_session, userchannel |
| Commands | command, command_acl |
| Files | downloaded_file, uploaded_file, file_acl |
| IAM | user, group, membership |
| Monitoring | metric, event, event_session, event_subscription, alert, alert_rule, activity, proc |
| Security groups | security_group, security_group_assignment, security_group_snapshot, firewall_chain, firewall_rule |
| Network | access_policy, access_rule, proxy_server, proxy_profile, network, subnet, pool, interface, host |
| DNS | dns_server, dns_view, domain, domain_group, record, zone |
| DHCP | dhcp_server, dhcp_session, lease |
| PKI | authority, certificate, sign_request, revoke_request |
| Registration | registration_method, registration_token |
| Workspace | workspace, preferences, webhook, note |
| Packages | package, package_entry |
| Approvals | approval_request |
Wildcards
| Scope | Meaning |
|---|---|
* | All resources and all actions (full access) |
{resource}:* | All actions for a specific resource |
Scope selection
Scopes are selected in two steps: choose a resource, then select the actions for that resource. You can also select All Access to grant the wildcard * scope.
Selected scopes are displayed as color-coded tags by action type.
Choose the minimal scopes necessary for your needs.
Token detail
Click on a token in the list to view its detail screen.
Token management
- Activate or deactivate the token using the toggle button in the top right corner.
- Manage the following items:
| Function | Description |
|---|---|
| Update token | Modify the token’s name, expiration, and scopes. |
| Delete token | Permanently delete the token. |
| Duplicate token | Create a copy with the same scopes, ACL rules, and expiration. |
| Allowed commands | Restrict which commands the token can execute. |
| Allowed file operations | Restrict which file operations the token can perform. |
| Allowed servers | Restrict which servers the token can access. |
Duplicate token
Click Duplicate to create a copy of the token. The duplicated token inherits the original token’s scopes, ACL rules, and expiration. The new token name has a “(copy)” suffix.
ACL rules
ACL (Access Control List) rules provide fine-grained control over what the token can do beyond scope-level permissions. Each ACL type restricts a specific aspect of token usage.
Important: Command/File/Server ACLs are only effective when the token has the relevant scopes granted. Without the corresponding scopes, the token cannot access the feature even if ACL entries are registered. Conversely, if the relevant scopes are granted but no entries are registered for an ACL type, no access is granted for that type. To allow access, grant the required scopes and register at least one entry for the corresponding ACL type.
Allowed commands
Allowed commands control which commands can be executed with the token.
- If no commands are registered: No commands can be executed
- If at least one command is registered: Only registered commands are executable
Each command entry has the following fields:
| Field | Description |
|---|---|
| Command | The command to allow. Supports wildcards (*). |
| Username | The user to run the command as. * for all users; leave empty for the token owner. |
| Groupname | The group context for command execution. * for all groups; leave empty for no restriction. |
Allowed file operations
Allowed file operations control which file transfer operations (upload/download) the token can perform.
- If no file operations are registered: No file operations can be performed
- If at least one file operation is registered: Only registered file operations are allowed
Each file operation entry has the following fields:
| Field | Description |
|---|---|
| File path | The file path to allow. Supports wildcards (*). |
| Action | The operation type: upload, download, or all. |
| Username | The user to perform the file operation as. * for all users; leave empty for the token owner. |
| Groupname | The group context for the file operation. * for all groups; leave empty for no restriction. |
Allowed servers
Allowed servers control which servers the token can access.
- If no servers are registered: No servers can be accessed
- If at least one server is registered: Only registered servers are accessible
Add servers by selecting from the server list.
Security best practices
- Principle of least privilege: Grant only the scopes necessary for the token’s intended use.
- Rotate tokens regularly: Set expiration dates and create new tokens before old ones expire.
- Configure ACL rules: Restrict allowed commands, file operations, and servers to minimize risk.
- Store tokens securely: Use encrypted secrets in your CI/CD platform.
- Revoke unused tokens: Deactivate or delete tokens that are no longer needed.