How do you give an AI agent an API key that can't touch everything?

TL;DR

Don't hand an AI agent your full access key. Every Orgo API key has three settings: a scope (all workspaces, one workspace, or one computer), an access level (full access, read only, or custom levels across eleven permission groups), and an expiry (from 1 day up to a year, or none). For an agent, make a workspace or one-computer key with only the groups it needs, give it an expiry, and rotate it by making the new key before you revoke the old one. A program running on an Orgo computer can use the computer's own key, which Orgo makes, rotates and revokes for you. That key isn't held to its computer, so treat it like an account key.

What is a scoped API key for an AI agent?

A scoped API key is a credential that reaches only part of your account. In Orgo, scope decides which workspaces or computers a key can touch, and permissions decide which endpoints it can call inside that scope. Orgo checks both on every request, before the endpoint runs. A call outside the key's permissions answers 403 with code: "key_permission", and the error message names the group and level the key would need.

That matters for agents because an agent acts on whatever its key allows. If the key can delete computers, invite people or buy credits, a confused or prompt-injected agent can too.

What are the three settings on an Orgo API key?

A new key made in Settings, API keys defaults to a 90 day expiry. The key's value is shown once, when you create it.

Which scope should an agent's key have?

A one-computer key can still start, stop, restart, suspend and resume its computer, and drive its screen, shell and Desktop API. Ask for another computer and it answers 403 with code: "computer_scope_mismatch".

Making a workspace key revokes the computer keys on that workspace's computers (see below). If a program on one of those computers reads ORGO_API_KEY, switch it to the new key first.

Which permissions does an agent actually need?

A restricted key has a level in each of eleven groups: none, read, or write (write includes read). A group you leave out of a custom key is none.

Most computer-use agents need two groups: computers to start and stop their machines, and control to click, type, run commands and take screenshots. An agent that calls Orgo's hosted agent through POST /api/v1/chat/completions also needs ai at write. Leave members, billing and keys at none unless the agent's job is literally managing those.

Three details are easy to miss:

• Read is not always harmless. Control read takes screenshots of a computer's screen and reads files on it.
• A workspace key can't have members at write. Asking for it answers 400 with code: "invalid_permissions", the same code as an unknown group or level.
• Custom with write in every group is still a restricted key, not full access. It can't make a full access key, and it can't call the endpoints reserved for you signed in.

Here is a workspace key for an agent that runs and drives computers in one workspace, expiring in 30 days:

curl -X POST https://www.orgo.ai/api/keys \
  -H "Authorization: Bearer $ORGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Fleet agent",
    "workspace_id": "'"$WORKSPACE_ID"'",
    "permissions": { "computers": "write", "control": "write" },
    "expires_in_days": 30
  }'

Send computer_id instead of workspace_id to bind the key to one Linux computer.

What is a computer key, and should my agent use it?

A computer key is a key Orgo makes for one Linux computer and writes onto it as ORGO_API_KEY, so an agent running there can call Orgo. Orgo makes one when a template's secrets declare orgo_api_key, for a curated template or one of your own, when you own the workspace, nobody else can use it, and you create the computer signed in or with a full access key for your whole account that never expires.

That last row is the one that surprises people. Anyone who can use the computer is root there and could read the key, so Orgo revokes it when an invite is accepted (whatever its access), a share link is claimed, a workspace key is made, someone connects the workspace through an MCP sign-in, an Invoicing client key is made or rotated for it, an agent account that owns it is claimed, or the computer moves into a shared workspace. Orgo also sweeps every 15 minutes for keys that may no longer stay. Programs that relied on ORGO_API_KEY then stop reaching Orgo.

Treat the key on a computer as seriously as an account key, and don't assume it stops at that computer. Keep what it can reach small: run that computer on an account that holds only what the agent needs. When a program must stay on one computer, make it a one-computer key instead, which Orgo holds to that computer, and leave orgo_api_key out of the template.

There is one more gotcha. Because anything that controls a computer can read its key, a restricted key or one that expires can't control a computer that holds its own key. Its control and AI calls about that computer answer 403 with code: "computer_key_held". Start, stop and get still work. Use a full access key that never expires for that computer, or sign in.

How do you rotate an agent's key without downtime?

Orgo never rotates a key you made, because it can't reach where you keep it. Replace one in three steps:

1. Create a new key with the same permissions and scope.
2. Update every agent and service that uses the old key.
3. Revoke the old key with DELETE /api/keys/{id}.

Both keys work until you revoke the old one. Orgo emails the account 7 days and 1 day before a key you made expires. Past its expiry, the key answers 401 with code: "key_expired" everywhere, and a WebSocket closes with code 4001. A key that expires can only make keys that expire no later than it does.

For the computer key, a program on the computer should read ORGO_API_KEY from /root/.orgo-secrets.env first and /root/.env when that file is missing or has no key, and read it again after a 401, then retry once. In a shell, sourcing /root/.env alone is enough: it sources /root/.orgo-secrets.env last, so it always gives the newest value. Both files are readable by root only.

# Run as root on the computer. Set COMPUTER_ID to the computer's UUID.
call_orgo() {
  . /root/.env
  status=$(curl -s -o /tmp/orgo-out.json -w '%{http_code}' "$@" \
    -H "Authorization: Bearer $ORGO_API_KEY")
  if [ "$status" = "401" ]; then
    . /root/.env   # the key may have rotated: read it again
    status=$(curl -s -o /tmp/orgo-out.json -w '%{http_code}' "$@" \
      -H "Authorization: Bearer $ORGO_API_KEY")
  fi
  cat /tmp/orgo-out.json
}
 
call_orgo "https://www.orgo.ai/api/computers/$COMPUTER_ID"

A 401 that persists after a fresh read means the key was revoked, not rotated. A 503 with code: "key_rotation_failed" means Orgo couldn't write the new secret, usually because the computer isn't running; nothing changed, so retry after the Retry-After seconds.

What errors will a scoped key return?

FAQ

Can a restricted key make a full access key? No. A key can never make or change keys past its own access, and even a custom key with write in every group can't make a full access key. It answers 403 with code: "key_escalation".

Is a read-only key safe to give an agent? Safer, not harmless. Control read takes screenshots of a computer's screen and reads files on it, so treat read access to a computer like read access to everything on it.

What happens to the computer key if I invite a teammate? Orgo revokes it and takes it off the computer when the invite is accepted, whatever access the invite gives. Anything on that computer that used ORGO_API_KEY stops reaching Orgo.

Can a one-computer key work on a Windows or Mac computer? No. One-computer keys are for Linux computers only; any other computer answers 400 with code: "computer_scope_unsupported".

What happens when I revoke a one-computer key that could control its computer? Orgo changes the computer's VNC password and Desktop API token, and open screen viewers close. Until the change finishes, Get VNC password answers 503 with code: "vnc_rotation_pending", so fetch the password again rather than reusing a stored one.

Where can I see which keys reach a computer? In Settings, API keys, on the computer's General tab, or with GET /api/keys?computer_id={id}.

Related

• Embed an AI agent computer in your app
• The Orgo computer use API
• Orgo MCP for AI agents
• Orgo templates and triggers
• Scale AI agent computers to thousands
• Can an AI agent sign up for its own cloud computer? (its signup key is full access for the whole account; narrow it with the steps above)

Sources

• Key scopes and computer keys
• API key permissions
• Key expiry and rotation