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 choose New key. A key carries a name, an optional description, an access level, a lifetime, and optionally a list of addresses it may be used from.
| Access | What it allows |
|---|---|
| Read-only | State, usage, images and logs. Nothing changes. The recommended starting point |
| Operate instances | Read, plus the power actions on an instance, and creating or deleting one. The exact list is in What Operate instances covers |
The name has to be different from every other key on this host, and the dialog says so rather than saving a second key you could not tell apart.
Lifetime offers 7 days, 30 days, 90 days and 1 year, defaults to 90, and you have to choose one. The host would accept a key that never expires, but the console does not offer it, so every key you create here has an end date. Plan for that: the automation that uses the key stops working on that date, with no warning beforehand, and expiry is the most likely reason a key that worked last month is refused today. Rotate it before the date lands.
Restricting the key to a list of CIDR ranges means a stolen key is useless from anywhere else. Address restriction covers how that matching works.
Using a key
Section titled “Using a key”Send the key as a bearer token: an Authorization header on each request,
carrying the word Bearer and then the key.
Errors carry a stable code for programs alongside a human-readable message,
so automation can branch on the code rather than parse prose.
When a key is refused
Section titled “When a key is refused”Every problem with a key looks the same from the outside: a 401 with the code
UNAUTHORIZED and the message invalid or expired api key. An expired key, a
revoked key, a mistyped key and a key used from an address outside its restriction all
produce exactly that answer. The host does not tell them apart on purpose, because a
distinct response for each would confirm to an attacker whether a token is real.
The evidence is on the API Keys page: the key’s expiry and its last-used time. Check those before you debug anything else. One limit to know going in: an expired key does not record a last-used time, so the key’s own record cannot tell you whether it was never used or was used after it expired.
Address restriction
Section titled “Address restriction”The CIDR list is matched against the peer address of the connection itself, never against a forwarded header. A client cannot be talked past the list by naming a different source in a header. It also means that if connections reach the host through a proxy, the address that has to be on the list is the proxy’s.
IPv4 and IPv6 never match each other, so a list of IPv4 ranges does not admit an IPv6
connection. 0.0.0.0/0 admits every IPv4 source, but it never matches an IPv6 one.
If a key is restricted and the host cannot work out the peer address at all, the
request is refused.
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 Operate instances covers
Section titled “What Operate instances covers”The higher access level is a fixed allowlist of actions, and everything off that list is denied. A key at this level may read, may send the power actions to an instance: boot, shutdown, reboot, pause, resume, and the power button, and may create and delete whole machines.
It may not change what a machine is. Editing its configuration, its network interfaces or its volumes, reinstalling it, snapshotting or restoring it, exporting it, and ingesting an image are all outside what any key can do. Those need an administrator signed in to the console.
The practical rule: a key drives a machine’s power state and can create or delete a whole machine, but it never changes what a machine is.
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. What a key may change is narrow: create a machine, delete one, or send a machine’s power actions. Configuration edits, NICs, volumes, reinstall, snapshots and transfer export are out of reach. Those stay with an administrator signed in to the console.
Rotating and revoking
Section titled “Rotating and revoking”Revoke a key from the same page when it should stop working now. Any client using it loses access immediately, and nothing replaces it.
Rotate is a different operation, and it is the renewal path. It creates a replacement key with the same name, the same access level and the same address restriction, gives it a fresh lifetime, and deletes the old key in the same transaction. The new secret is returned once, like any other, and the old value stops working at that moment. Use rotate when a key is approaching its expiry or when you only need a new secret: it carries the restriction you already set over to the new key, so you do not have to remember and re-enter it.
A key you lose the secret for does not have to be revoked and rebuilt. Rotating it gives you a secret you can copy, with the access unchanged.