Manage personal API tokens
Create personal API tokens for scoped calls to the Alpacon API.
Token restrictions
Personal API tokens allow programmatic access to the Alpacon API. 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.
New personal API tokens cannot hold command-execution or file-transfer scopes. Existing tokens with those scopes keep working without a work session. Use a service token for automation and CI.
Where to find personal API tokens
Click your account card at the bottom of the left sidebar and select My API tokens to manage your tokens.
Token list
The list shows each token’s name, number of scopes, expiration date, and last update.
Create token
- Click the Add button.
- Set the token Name.
- Set Expiration (7 days, 30 days, 90 days, 1 year, or custom). Every new token expires, no later than your workspace’s maximum token lifetime.
- 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 a personal API token can perform. The format is {resource}:{action}.
Available resources
Every resource and action a token can hold is listed in the scopes reference, together with what each one permits and which ACL narrows it. In the scope selection UI you see the subset your own roles let you grant.
Wildcards
| Scope | Meaning |
|---|---|
{resource}:* | All actions for one resource |
*:{action} | One action across every resource |
A wildcard is accepted only when your own permissions cover that wildcard. A personal API token can’t be given *, or any wildcard that covers running commands or moving files, such as command:*, uploaded_file:*, downloaded_file:* or *:create. A token issued with one of them keeps it. See Scope format.
Scope selection
Scopes are selected in two steps: choose a resource, then select the actions for that resource. To give every action on a resource, pick All actions for it. A personal API token isn’t offered it for Command, Uploaded file and Downloaded file.
Selected scopes are displayed as color-coded tags by action type.
Choose the minimal scopes necessary for your needs.
Quick presets
When creating a token, you can apply a quick preset—a bundle of scopes for a common workflow—instead of picking each scope individually. Presets are available at creation time only; on an existing token you edit scopes directly. The scopes reference lists every preset and the scopes it grants.
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 and expiration. (Scopes are edited inline—see below.) |
| 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. |
Edit scopes: change the token’s scopes inline on the detail page, then click Save to apply.
Activity log: the detail page includes an Activity view showing this token’s usage history.
While a token is inactive, the Add button for ACL rules is disabled. Re-activate the token first to add entries.
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.
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. The object narrowing column in the scopes reference shows which ACL type applies to each resource.
Allowed commands
Allowed commands control which commands can be executed with the token. They apply to a personal API token that already holds command scopes.
- 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. |
A command entry is matched against the command line you submit, not the command that runs as root, so an entry for a privileged command must include the sudo prefix, and a trailing * requires at least one argument. See Token command matching before writing entries for sudo commands.
Allowed file operations
Allowed file operations control which file transfer operations (upload/download) the token can perform. They apply to a personal API token that already holds file transfer scopes.
- 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 an encrypted secret store. For unattended CI/CD, use a service token.
- Revoke unused tokens: Deactivate or delete tokens that are no longer needed.