Skip to main content
Every API key reaches all your workspaces, one workspace, or one computer. That is its scope. Its permissions, described in API key permissions, apply inside that scope. Two kinds of key reach one computer:
  • A computer key is the key Orgo makes for a computer and puts on it as ORGO_API_KEY, so what runs there can call Orgo. Orgo manages it.
  • A one-computer key is a key you make for one computer, to hand to a contractor or an embed.

​
Key scopes

A workspace key reaches only that workspace and the computers and files in it, whatever its permissions. With API keys access it manages the keys of its workspace, but never a one-computer key, as described in What a workspace key can manage. What else it can and can’t call is described in What a workspace-scoped key can do. A one-computer key reaches only its computer, as described in One-computer keys for contractors and embeds.

​
Computer keys made by Orgo

A computer key is a key for your account that Orgo makes for one Linux computer. Orgo writes it onto the computer as ORGO_API_KEY, so a program there, such as an agent or the Bops runner, can call Orgo as you. It is named Computer key for <computer name>, and each computer has at most one.
  • Made for templates that ask for it. A template whose secrets declare orgo_api_key gets a new computer key when the computer is created. It is never a key from your vault. This happens only for a curated template or one of your own, only when you own the workspace and nobody else can use it, and only when you create the computer signed in or with a full access key for your whole account that never expires. The Bops app also puts one on a computer its bots run on.
  • Bound to its computer. It calls only the endpoints its computer’s work needs, listed in What a computer key can call.
  • Managed by Orgo. Nobody can change its permissions, scope or expiry: PATCH /api/keys/{id} answers 409 with code: "managed_key". It never expires. Its secret rotates by itself on use once it is 30 days old, as described in How a computer key rotates.
  • Revoked with its computer. Deleting the computer, or its workspace, revokes its key.
  • Copies get their own. A clone, a fork, or a backup or snapshot restored as a new computer starts from the source’s disk, which holds the source’s key. So Orgo takes the source’s key back before it copies. The source gets a new key, and the copy gets its own. The copy gets none where it may not have one, or when a narrower key made the copy, as described in the next point. No key is live on two computers. If Orgo can’t take the key back, the copy answers 503 with code: "copy_key_busy" and nothing is copied.
  • Never from a narrower key. The computer key has full access to its computer and never expires, so a restricted key, a key that expires, a workspace key or a one-computer key never causes one. A template launched with one of them gets no ORGO_API_KEY, and a copy made with one gets no key.
  • Never in someone else’s hands. A computer holds its key only while nobody but you can use its workspace, as described in When Orgo revokes a computer key.
On the computer, a key a template asked for is in /root/.env from create. Every later write, such as a rotation or the Bops app’s, goes to /root/.orgo-secrets.env. A program should read /root/.orgo-secrets.env first. How to re-read it after a 401 is described in Re-read the key after a 401.

​
What a computer key can call

A computer key calls only what its computer’s work needs: control of its own computer, and the Bops data its runner reads and writes. Any other endpoint answers 403 with code: "computer_key". It never makes or changes keys, never lets anyone else in (no invites, share links, roles or transfers), and never reaches your billing. Rows marked “Any key for one computer” are open to one-computer keys too. Rows marked “Its own computer’s key (Bops)” serve the Bops runner on the computer, for the Bops bots that work there.
Orgo is rolling out the check that holds a computer key to its own computer and the Bops bots that work there. Orgo turns it on for every account at once. Until then, a computer key can make the calls above about your other computers and their bots too.

​
Narrower keys on a computer with its own key

Whatever controls a computer can read its computer key in /root/.orgo-secrets.env. So a restricted key, or a key that expires, can’t control a computer that holds its own key, or has one on its way after a copy. Its Control and AI endpoints about that computer (the screen, files, commands, terminal and agent), the Desktop API proxy and its screen password answer 403 with code: "computer_key_held". Its Computers endpoints, such as start, stop and get, still work. Use a full access key that never expires, or sign in. The answer is shown in Computers that hold their own key.

​
When Orgo revokes a computer key

The key is your whole account’s, and anyone who can use the computer is root there and could read it. So a computer may hold its key only while:
  • it is a Linux computer of the workspace’s owner,
  • nobody else is a member of the workspace, in any role, and no invite or share link to it is open,
  • no workspace key, Invoicing client or MCP sign-in reaches the workspace,
  • and no one-computer key is bound to that computer.
Orgo revokes the key, and takes it off the computer, when any of that stops being true: an invite is accepted, a share link is claimed, a workspace key is made, the computer moves into a shared workspace, or the workspace or computer goes to another account. A computer that must not hold a key never gets one. Every 15 minutes Orgo also takes back any key that may no longer stay.
Inviting anyone to a workspace, even with view-only access, revokes the computer keys of its computers. Programs there that use ORGO_API_KEY, such as Bops bots, stop reaching Orgo.
You can revoke a computer key yourself, signed in or with a full access key for your whole account that never expires. Use Settings, API keys, the computer’s General tab, or DELETE /api/keys/{id}. What runs on the computer stops reaching Orgo at once.

​
One-computer keys for contractors and embeds

One-computer keys are rolling out. Orgo turns them on for every account at once. Until then, POST /api/keys with computer_id answers 400 with code: "computer_scope_unavailable", and Settings shows no One computer choice.
A one-computer key reaches one Linux computer and nothing else. Use it when someone needs a computer but not your account:
  • A contractor works on one computer. Give them a key with Control write. Revoke it when the work ends.
  • An embed shows one computer in your app. Your server holds a one-computer key instead of an account-wide key, and reads the computer’s VNC password with it, as described in Embed computers. If your server leaks the key, it reaches only that computer.

​
What a one-computer key can and cannot do

  • It can call only the endpoints listed in Which endpoints a one-computer key can call, only about its own computer, and only at its permission levels. Anything else answers 403 with code: "computer_scope". Another computer answers 403 with code: "computer_scope_mismatch".
  • It can start, stop, restart, suspend and resume its computer. It can’t delete, resize, clone, fork or move it.
  • It can’t list, make or revoke keys, or reach your workspaces, files, templates, secrets or billing.
  • Only the Computers and Control groups matter for it. Settings offers only those two under Custom.
A one-computer key with full access or Control write is root on its computer. Whoever holds it can run commands there and read secrets saved on the computer.

​
Make a one-computer key

In Settings, API keys, choose New key, then Reaches: One computer, and pick the computer. From a computer’s General tab, New key under Keys for this computer opens the same sheet with that computer picked. With the API, send computer_id:
Set $COMPUTER_ID to the computer’s UUID. The answer is described in Create a key, with "scope": "computer" and the computer it is for.
  • Only you signed in, or a key for your whole account, can make, change or revoke one. A workspace key gets 403 with code: "account_key_required", even for a computer in its own workspace. A one-computer key gets 403 with code: "computer_scope", and a computer key 403 with code: "computer_key".
  • You need write access to the computer’s workspace. A view-only member gets 403 with code: "workspace_read_only" and This workspace is view-only. Ask the owner for write access (workspace_read_only).
  • Only Linux computers. Any other computer answers 400 with code: "computer_scope_unsupported".
  • Not on a computer that holds its own computer key, because the Bops bots there would stop. That answers 409 with code: "computer_key_in_use", and Orgo keeps the computer’s own key.

​
Revoking changes the screen password

Revoking a one-computer key that could control its computer (full access, or Control write) changes the computer’s VNC password and Desktop API token. So does such a key expiring, or a change that takes away its Control write. Screen viewers opened with the old password close. The change runs right after the revoke. Until it is done, the old password is refused, and Get VNC password answers 503 with code: "vnc_rotation_pending". Fetch the password again rather than reuse one you stored.

​
How long a one-computer key lasts

  • It keeps working through a stop, a wake and a restore in place.
  • When its computer moves to another workspace, the key moves along if the person who made it owns that workspace or is a member there. Otherwise the key is deleted.
  • It is deleted with its computer. A copy of the computer (a clone, a fork, or a restore as a new computer) has no one-computer keys.
  • It is deleted when its computer is handed to another account, when the member who made it leaves the workspace, and after it expires.
  • Its computer never changes. PATCH /api/keys/{id} with computer_id or workspace_id answers 400 with code: "computer_scope_fixed". Make a new key for another computer.
When its computer is gone, the key answers 401 with code: "key_computer_gone". When its computer was deleted, 403 with code: "computer_deleted".

​
Where to see computer keys

  • Settings, API keys. Your keys, each with what it reaches. A one-computer key says which computer. Computer keys are listed on their own under Computer keys, each linked to its computer.
  • The computer’s General tab. For the owner of a Linux computer, Orgo key shows its computer key, when it has one, with Revoke. Keys for this computer lists its one-computer keys with Revoke and New key. The workspace’s owner sees every key made for the computer and who made it. A member sees only their own.
  • The API. GET /api/keys?computer_id={id} lists the keys bound to one computer. GET /api/computers/{id}/keys and DELETE /api/computers/{id}/keys/{keyId} list and revoke them per computer, for you signed in or a key for your whole account with API keys read or write.