Access Tokens
The Tokens tab lets you create and manage scoped API tokens directly from the web dashboard. Scoped tokens let you grant limited access to specific VMs — for CI pipelines, automation scripts, or team members — without sharing your master authentication token.
Overview
The tab follows the same layout as other tabs: a toolbar with a New Token button, search bar, and filter pills, a full-width token table, and a detail panel that slides in from the right when you select a row.
The Tokens tab is visible only when you are authenticated with the master token. Scoped tokens do not have access to manage other tokens.
Access Levels
Each token has one of two access levels:
| Level | What it can do |
|---|---|
| Operator | Start, stop, pause, resume, restart VMs. Read VM info, status, and snapshots. Cannot change configuration. |
| Admin | Full access — all Operator operations plus editing VM configuration, disks, networks, and snapshots. Admin tokens scoped to All VMs can also create new VMs, and can be granted optional extended access to Templates, Networks, and Images. |
Token Table
Each row in the table shows:
- Status dot — green (Active), grey (Disabled), or red (Expired)
- Label — the token's human-readable name
- Virtual Machines — which VMs the token can access; shows All VMs with a star icon if unrestricted. An amber ⚠ icon appears if any named VM no longer exists.
- Scope — the access level badge (Operator or Admin)
- Status — Active, Disabled, or Expired text badge
- Expiry — expiry date (amber if ≤ 7 days, red if expired, Never if no expiry set)
- Last Used — relative time since the token was last used (e.g. 2h ago, 3d ago, or —)
- Actions — inline row buttons: Edit, Disable/Enable, and Revoke
Click any row to open the detail panel for that token.
Filtering and Searching
Use the filter pills to narrow the view:
| Filter | What it shows |
|---|---|
| All | Every token |
| Active | Valid, enabled tokens only |
| Disabled | Manually disabled tokens |
| Expired | Tokens past their expiry date |
Type in the search bar to filter by label or VM name.
Creating a Token
Click + New Token in the toolbar to open the Create Token dialog.
| Field | Description |
|---|---|
| Label | A name to identify this token (e.g. CI Pipeline or Dev Laptop) |
| Access Level | Select Operator or Admin using the scope cards |
| Virtual Machines | Check All VMs to grant access to every VM, or select individual VMs from the list |
| Expiry | Toggle Expires on and pick an expiry date, or leave it off for a token that never expires |
Click Create Token to generate the token. A Token Reveal dialog appears immediately showing the secret — this is the credential used in the X-Auth-Token header.
Important: The secret is shown only once and cannot be retrieved later. Copy it before closing the dialog. The Token ID can be viewed at any time from the detail panel and is used for management operations (rotate, disable, enable, revoke).
Editing a Token
Click Edit on a row, or click the Edit button inside the detail panel, to open the Edit Token dialog. You can update the label, VM scope, access level, and expiry.
Editing a token does not change its secret. When editing an Admin+All VMs token, the Extended Permissions section also appears so you can update which management areas it can access.
Extended Permissions
When creating or editing an Admin token scoped to All VMs, an Extended Permissions section appears with three optional checkboxes:
| Permission | What it grants |
|---|---|
| Templates | Templates tab visible — browse, deploy, and manage VM templates |
| Networks | Networks tab visible — create, edit, and delete host virtual networks |
| Images | Images tab visible — download and manage OS images |
Each defaults to unchecked. Enabling a permission makes the corresponding tab visible when the token is used to log in. If the scope or VM scope changes away from Admin+All VMs, all extended permissions are cleared automatically.
The detail panel shows which extended permissions are active for a selected token with ✓/— badges next to each permission name.
Rotating a Token Secret
Click Rotate Secret in the detail panel to regenerate the bearer secret. A confirmation dialog explains that the current secret will stop working immediately. After confirming, the new secret is shown once in the same reveal dialog used at creation — copy it before dismissing. All other token settings are unchanged.
Disabling and Enabling
Click Disable on a row to temporarily block the token without deleting it. A disabled token is rejected by the API until re-enabled. Click Enable on a disabled row to restore access. Changes take effect immediately.
Revoking a Token
Click Revoke on a row to permanently delete the token. A confirmation dialog asks you to confirm before proceeding. Once revoked, the token is removed from the table and any client using it will lose access immediately. This cannot be undone.
The detail panel also provides a Revoke button with a higher-friction confirmation that requires you to type REVOKE — useful when you want to double-check before permanently removing an important token.
Detail Panel
Clicking a row opens the detail panel on the right, showing:
- Label and creation date with the current status badge
- Status — Active, Disabled, or Expired with a colour indicator
- Access Level — scope with description
- Virtual Machines — full list of VMs in scope. An amber warning appears if any named VM no longer exists.
- Expiry — expiry date or Never expires
- Last Used — relative time and IP address of the last request
- Token ID — the management identifier (safe to share); click to copy
The panel provides Edit, Rotate Secret, Disable/Enable, and Revoke action buttons.
Scoped Token Indicator
When you log in to the web dashboard using a scoped token instead of the master token, an amber pill appears in the header toolbar showing the token's access level (e.g. Operator or Admin). Click the pill to see a summary: label, access level, VM count, and expiry.
Tabs that are restricted for the current token — such as Tokens, Templates, Networks, and Images — are hidden automatically. Configuration panels open in read-only mode for Operator tokens.
Admin tokens scoped to All VMs additionally show the Quick VM and New VM create buttons in the VMs tab. If the token also has extended permissions, the corresponding tabs (Templates, Networks, Images) become visible.
Using a Scoped Token
Pass the token's secret in the X-Auth-Token header for any HTTP API request, or use it with the vpvm CLI:
Requests that target VMs outside the token's scope, or operations beyond its access level, are rejected with an error.