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 Keys under Host and choose Create key. The page has two views, API keys and SSH keys, and shows one at a time; this section is about API keys, and SSH keys is below. A key carries a name, an optional Purpose, 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 permitted instance logs. Nothing changes. The recommended starting point |
| Operate instances | Read, plus instance power actions and creating or deleting a machine; from Free 1.3, CPU and memory adjustments too. 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. The Keys page can filter by Expiring soon, Expired, and Never used.
Restricting the key to a list of CIDR ranges (the Restrict source field, empty for any source) 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.
Troubleshooting and MCP in Free 1.3
Section titled “Troubleshooting and MCP in Free 1.3”From Free 1.3, keys can read diagnosis findings, the recent diagnostic error index, instance launch attempts and their runtime/storage logs, AppVM workload logs, metrics, capacity, operations and host-image status. The error index provides request/boot correlation, not raw host run logs or a downloadable diagnostic report. Reading host-image status does not permit staging, discarding or rebooting; those remain console-session actions.
To connect Claude Code, Cursor, VS Code or another supported client with the same key, follow Connect an AI agent (MCP). A read-only key does not see write tools; an Operate instances key retains the same narrow instance scope as REST, including the resource-only CPU and memory adjustment route in Free 1.3.
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 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”All read responses hide the main account’s password, additional users’ passwords and the raw user-data document, for API keys and administrator sessions alike. The Cloud-Init panel shows only whether a password is set and whether custom user-data is Set (hidden). Keep your own copy before submitting them.
An API key cannot create a VM by referencing a template’s hidden user-data; that requires an administrator session.
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.
From Free 1.3, a key at this level may also change only CPU and memory through
PATCH /api/instances/{id}/resources, using the current revision. Stopped/live rules
and bounds still apply. In MCP, use set_instance_resources; see
CPU and memory adjustments.
General configuration edits, hot-add ceilings, PCI devices, network interfaces, volumes, secrets, reinstall, snapshots, restore, export and image ingestion remain outside the key’s permissions. Those need an administrator signed in to the console.
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, send its power actions, or adjust only its CPU and memory from Free 1.3. General configuration edits, hot-add ceilings, PCI devices, secrets, 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. To revoke several at once, tick their rows and use the toolbar. Each revocation runs in turn, and any that fail are listed with the reason instead of stopping the rest.
Edit name, purpose, source in a row’s menu changes those three fields and keeps the same secret. The access level cannot be edited: create a new key to change 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 a fresh 90-day 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.
SSH keys
Section titled “SSH keys”The SSH keys view holds public keys you want to reuse when you create machines,
so you do not paste the same line each time. Add key takes a name and a public
key; the list shows each key’s name, type, fingerprint, and when it was added. The
file picker From this computer… reads the public key out of a .pub file.
Only the public half is stored. A private key is refused, a line that is not a valid OpenSSH public key is refused, and a key whose fingerprint is already saved is refused as a duplicate. When you create a machine or a template, choose from the saved keys in its access settings. Deleting a saved key does not affect machines already created with it, because the key line was copied into the machine when it was created; it only stops being offered for new ones. Tick several rows to delete a batch.
Saved SSH keys are managed from the console only. An API key cannot read or change them.