Skip to content

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.