--- title: "Manage personal API tokens" description: "Create personal API access tokens for scoped Alpacon API calls. Set scopes and expiration, review server ACLs, and use service tokens for unattended CI/CD." --- > Full documentation index: https://docs.alpacax.com/llms.txt # Manage personal API tokens # 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](/use/iam/applications/service-tokens/) 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 1. Click the **Add** button. 2. Set the token **Name**. 3. 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. 4. Select **Scopes** to define which resources and actions the token can access. 5. Click **Create**. 6. 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](/reference/scopes/), 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](/reference/scopes/#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](/reference/scopes/#presets) 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](/reference/scopes/#all-resources) 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](/reference/tokens/command-patterns/) 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. Source: https://docs.alpacax.com/use/settings/api-tokens/