API keys
Updated
The console signs you in with a browser session. Automation uses an API key instead, so a script or another system can call the host without pretending to be a browser.
Creating a key
Section titled “Creating a key”Open API Keys under Host and create one. Choose its access level:
| Access | What it allows |
|---|---|
| Read | Reading host state: machines, images, networks, capacity, metrics |
| Read and write | The same, plus creating, changing, and deleting machines |
Using a key
Section titled “Using a key”Send it as a bearer token:
curl --request GET "https://virtainer.example.com/api/vms" \ --header "Authorization: Bearer vak_..."Errors carry a stable code for programs alongside a human-readable message,
so automation can branch on the code rather than parse prose.
Guest passwords are hidden from keys
Section titled “Guest passwords are hidden from keys”A key may end up in the hands of automation whose output you do not control, so machine responses to a key hide the cloud-init passwords they would otherwise carry: the main account’s password, every additional user’s password, and the whole raw user-data document, which repeats those same passwords verbatim.
An administrator signed in to the console still sees them, and they remain readable from the instance’s Cloud-init panel.
What keys cannot do
Section titled “What keys cannot do”API keys are scoped to the machine and workload endpoints on purpose. They cannot manage other API keys, and they do not reach the browser session endpoints, first-run setup, host power, console and exec, factory reset, network changes, or image ingestion. Those stay with an administrator signed in to the console.
Revoking
Section titled “Revoking”Revoke a key from the same page. Any client using it loses access immediately.