Skip to main content

Admin API Tokens

Overview​

The platform exposes a full admin REST API at https://<your-panel-domain>/api/v1/. Anything an administrator can do in the panel - list hypervisors, create users, deploy or migrate instances, manage backups - can also be done programmatically through this API. An admin API token is the credential that authenticates those calls.

Tokens are generated, listed, enabled, disabled and deleted from the management server's shell using the hvcli api:admin-token command. The token's secret value is shown exactly once, at creation time, and is never recoverable afterwards - only a hash of it is stored on the Master.

warning

An admin API token grants the entire admin API with the privileges of the admin user it is assigned to. Treat it like a root password: bind it to a single source IP, store it in a secrets manager, and rotate it periodically.

Concepts​

  • A token is a UUID-keyed record stored on the Master. Each token has a name, an optional description, the source IP it is bound to, an enabled/disabled flag, and the admin user it acts as.
  • The token ID (a UUID) is what you use to enable, disable or delete a token later. The token itself (the actual secret) is shown only at creation time and stored hashed - it cannot be read back, even by root.
  • Every token is IP-bound: a request carrying the token is rejected unless it arrives from the exact IP the token was created for. A leaked token is useless from any other machine.
  • Every token is assigned to an admin user. API calls made with the token run as that user, and admin audit logs record both the acting user and the token ID that authenticated the request. Create a dedicated admin account per integration (for example [email protected]) so audit trails stay readable.

Admin steps​

Generate a new token​

SSH into the management server and run:

hvcli api:admin-token generate

You will be prompted for:

  • IP address: the public IP the calls will come from (your automation host, CI runner, or integration server). Required and validated.
  • Name: a label for your own reference, for example Ansible-Provisioning.
  • Description: optional free text.
  • Admin user UUID: the ID of the admin user this token acts as. The user must already exist and be flagged as an admin - the command refuses non-admin users. You can find a user's UUID on their admin panel profile page URL.

Sample output:

Please copy the token below and save it somewhere safe, you won't be able to see it again.
Your new token is: 9f2c1e7a4b...

Copy the token into your integration's secret store immediately. If you lose it, generate a new one; there is no recovery flow.

Use the token​

Send it as a standard bearer token on every request:

curl -H "Authorization: Bearer <your-token>" \
     -H "Accept: application/json" \
     https://<your-panel-domain>/api/v1/hypervisors

Common failure responses:

ResponseMeaning
403 Unauthorized!No Authorization: Bearer header was sent.
401 Unauthorized!Token is wrong, disabled, or the request came from an IP other than the one the token is bound to.
403 UnauthorizedThe token's assigned user is no longer an admin.

List existing tokens​

hvcli api:admin-token list

Sample output:

+--------------------------------------+----------------------+---------------------+----------------+---------+------------------------+
| ID                                   | Name                 | Description         | IP Address     | Enabled | User Email             |
+--------------------------------------+----------------------+---------------------+----------------+---------+------------------------+
| 550e8400-e29b-41d4-a716-446655440000 | Ansible-Provisioning | Prod automation     | 203.0.113.45   | Yes     | [email protected] |
| 3d8d8e80-2b97-11ed-a261-0242ac120002 | Legacy-Scripts       | Old cron scripts    | 198.51.100.10  | No      | [email protected]  |
+--------------------------------------+----------------------+---------------------+----------------+---------+------------------------+

The ID column is what you pass to the enable, disable and delete commands.

Enable, disable or delete a token​

# Enable a previously disabled token
hvcli api:admin-token enable 550e8400-e29b-41d4-a716-446655440000

# Temporarily turn a token off without deleting it
hvcli api:admin-token disable 550e8400-e29b-41d4-a716-446655440000

# Delete a token permanently
hvcli api:admin-token delete 550e8400-e29b-41d4-a716-446655440000

Disabled tokens stay in the list but every API call using them is rejected. Deleting is permanent.

Security best practices​

  1. One token per integration, each on its own dedicated admin account. Never share one token between systems - you lose the ability to revoke or audit them independently.
  2. Bind to the real source IP and update the token (delete + regenerate) when the calling host moves; the IP check is your strongest protection against a leaked token.
  3. Store tokens in a secrets manager (Vault, environment secrets, CI credential store), never in code or plain-text config committed to a repository.
  4. Rotate tokens every 6-12 months: generate a new one, swap it into the integration, verify, then delete the old one.
  5. Disable first, investigate second if you suspect a leak. Disabling is instant and reversible; check the admin audit log for what the token did before deciding to delete.
  6. Prefer the user API for tenant automation. Admin tokens are for platform-level operations. If a customer wants to automate their own resources, point them at their per-user API credentials instead of issuing an admin token.