> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orgo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Key scopes and computer keys

> Limit a key to one workspace or one computer, and how the key Orgo puts on a computer works.

Every API key reaches all your workspaces, one workspace, or one computer. That is its scope. Its permissions, described in [API key permissions](/api-reference/api-keys/permissions.md), 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

| Scope | In Settings | With `POST /api/keys` | `scope` in answers |
| - | - | - | - |
| All workspaces | All workspaces | Send neither `workspace_id` nor `computer_id` | `account` |
| One workspace | One workspace | `"workspace_id": "<workspace UUID>"` | `workspace` |
| One computer | One computer | `"computer_id": "<computer UUID>"` | `computer` |

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](/api-reference/api-keys/manage.md#what-a-workspace-key-can-manage). What else it can and can't call is described in [What a workspace-scoped key can do](/api-reference/authentication.md#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](#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](#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](/api-reference/api-keys/expiry-and-rotation.md#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](#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](/api-reference/api-keys/expiry-and-rotation.md#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.

| Method | Path | Who | What it does |
| - | - | - | - |
| POST | `/api/bops/computer/active` | Its own computer’s key (Bops) | Tells Orgo the free Bops computer is in use so it is not suspended for sitting idle. |
| GET | `/api/bops/plan` | Its own computer’s key (Bops) | Returns the Bops plan, AI credit and free Bops computer, granting the free starting credit on first read. |
| GET | `/api/bops/settings` | Its own computer’s key (Bops) | Returns whether the account's Bops bots work in the cloud or on the Mac. |
| GET | `/api/computers/{id}` | Any key for one computer | Gets a computer with its status, hardware and connection details. |
| POST | `/api/computers/{id}/bash` | Any key for one computer | Runs a shell command on the computer and returns its output. |
| POST | `/api/computers/{id}/click` | Any key for one computer | Clicks at a point on the computer's screen. |
| POST | `/api/computers/{id}/drag` | Any key for one computer | Drags the mouse from one point to another on the computer. |
| POST | `/api/computers/{id}/exec` | Any key for one computer | Runs Python code on the computer and returns its output. |
| POST | `/api/computers/{id}/key` | Any key for one computer | Presses a key or key combination on the computer. |
| POST | `/api/computers/{id}/mouse-move` | Any key for one computer | Moves the pointer on the computer's screen without clicking. |
| POST | `/api/computers/{id}/resume` | Any key for one computer | Resumes a suspended computer where it left off. |
| GET | `/api/computers/{id}/screens` | Any key for one computer | Lists the screens on the computer. |
| POST | `/api/computers/{id}/screens` | Any key for one computer | Adds a screen to the computer. |
| GET | `/api/computers/{id}/screens/{screenId}` | Any key for one computer | Gets one screen on the computer. |
| GET | `/api/computers/{id}/screenshot` | Any key for one computer | Takes a screenshot of the computer's screen. |
| POST | `/api/computers/{id}/scroll` | Any key for one computer | Scrolls on the computer's screen. |
| POST | `/api/computers/{id}/type` | Any key for one computer | Types text on the computer. |
| GET | `/api/computers/{id}/vnc-password` | Any key for one computer | Gets the computer's VNC password and its Desktop API token. |
| POST | `/api/computers/{id}/wait` | Any key for one computer | Waits a number of seconds on the computer. |
| GET | `/api/desktops/{id}/proxy/{...path}` | Any key for one computer | Passes a read request through to the computer's Desktop API. |
| HEAD | `/api/desktops/{id}/proxy/{...path}` | Any key for one computer | Passes a read request through to the computer's Desktop API. |
| POST | `/api/desktops/{id}/proxy/{...path}` | Any key for one computer | Passes a request that acts on the computer through to its Desktop API. |
| PUT | `/api/desktops/{id}/proxy/{...path}` | Any key for one computer | Passes a request that acts on the computer through to its Desktop API. |
| PATCH | `/api/desktops/{id}/proxy/{...path}` | Any key for one computer | Passes a request that acts on the computer through to its Desktop API. |
| DELETE | `/api/desktops/{id}/proxy/{...path}` | Any key for one computer | Passes a request that acts on the computer through to its Desktop API. |
| POST | `/api/projects/{id}/access/log` | Its own computer’s key (Bops) | Records Bops bots' uses of apps and keys. |
| GET | `/api/projects/{id}/orbit/issues` | Its own computer’s key (Bops) | Lists the Bops workspace's Orbit issues. |
| POST | `/api/projects/{id}/orbit/issues` | Its own computer’s key (Bops) | Creates an Orbit issue, or updates the one already open for the same thread or ticket. |
| PATCH | `/api/projects/{id}/orbit/issues/{issueId}` | Its own computer’s key (Bops) | Updates an Orbit issue or adds notes to it. |
| PUT | `/api/projects/{id}/routines` | Its own computer’s key (Bops) | Saves many Bops routines at once and can delete the ones left out. |
| POST | `/api/projects/{id}/routines/{routineId}/runs` | Its own computer’s key (Bops) | Records the result of a Bops routine's run. |
| GET | `/api/secrets` | Its own computer’s key (Bops) | Lists the names of the account's saved secrets, never their values. |
| POST | `/api/secrets/call` | Its own computer’s key (Bops) | Calls a third party API with a saved secret without showing the secret. |
| GET | `/api/user/profile` | Its own computer’s key (Bops) | Shows the account's id, email, name and plan status. |
| WebSocket | `/desktops/{id}/ws/audio` | Any key for one computer | Streams the computer's sound. |
| WebSocket | `/desktops/{id}/ws/rtc` | Any key for one computer | Streams the computer's screen over WebRTC, with its mouse and keyboard. |
| WebSocket | `/desktops/{id}/ws/stats` | Any key for one computer | Streams the live statistics of a screen connection. |
| WebSocket | `/desktops/{id}/ws/terminal` | Any key for one computer | Opens a terminal on the computer. |
| WebSocket | `/desktops/{id}/ws/websockify` | Any key for one computer | Streams the computer's screen over VNC, with its mouse and keyboard. |

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.

> [!NOTE]
>
> 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](/api-reference/api-keys/permissions.md#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.

> [!WARNING]
>
> 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

> [!NOTE]
>
> 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](/guides/embed-vms.md). 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](/api-reference/api-keys/permissions.md#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.

> [!WARNING]
>
> 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`:

```bash theme={null}
curl -X POST https://www.orgo.ai/api/keys \
  -H "Authorization: Bearer $ORGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Contractor",
    "computer_id": "'"$COMPUTER_ID"'",
    "permissions": { "computers": "write", "control": "write" },
    "expires_in_days": 30
  }'
```

Set `$COMPUTER_ID` to the computer's UUID. The answer is described in [Create a key](/api-reference/api-keys/manage.md#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](/api-reference/computers/vnc-password.md) 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.

## Related pages

* [API key permissions](/api-reference/api-keys/permissions.md): what each group and level allows.
* [Create and manage API keys](/api-reference/api-keys/manage.md): every request and error code.
* [Key expiry and rotation](/api-reference/api-keys/expiry-and-rotation.md): expiry, reminders, and how a computer key rotates.
* [Get an identity token inside a computer](/guides/instance-identity.md): a short-lived token in place of a key file, coming soon.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.