Skip to main content
Every API key has access, a scope and an expiry. This page covers access: which endpoints a key may call. Scope (all workspaces, one workspace or one computer) is described in Key scopes and computer keys. Expiry is described in Key expiry and rotation. A key has full access, or it is restricted. A restricted key has a level in each of eleven permission groups. It can call only the endpoints listed for its groups, at their level, and nothing else. Orgo checks this on every request, before the endpoint runs. The same table drives the check and this page. You can also download the mapping as CSV: one row per method and path a key may call, with its group, level, and whether a one-computer key may call it.

​
Permission levels

Each group has one of three levels. Read is not harmless in every group. Control read takes screenshots of a computer’s screen and reads files on it. Secrets read lists the names of your secrets, never their values.

​
Presets

Settings, API keys offers three choices. The API takes the same three. Every key made before permissions existed has full access. So do the keys Orgo makes for its own apps, such as Bops for iPhone. A computer’s own key is held to a fixed list instead, described in What a computer key can call.
Custom with Write in every group is still a restricted key, not full access. It cannot call the endpoints described in Endpoints a restricted key never uses, and it cannot make a full access key.

​
Permission groups

The API names each group in lowercase. Settings shows the label.

​
When a key lacks the permission

A restricted key that calls an endpoint outside its groups is refused before the endpoint runs. Every endpoint answers 403 with code: "key_permission". The message names the call, and the group and level the key would need. Execute bash without Control write answers:
Make a key with the level the message names. An endpoint no restricted key may call says (it needs full access) instead: use a full access key or sign in, as described in Endpoints a restricted key never uses. The Computer Use API and threads answer in their OpenAI style envelope, with the same status and code: { "error": { "type": "permission_error", "message": "…", "code": "key_permission" } }. Scope is checked as well. A restricted key for one workspace can call only its groups’ endpoints, and only for that workspace. A key for one workspace never manages people or deletes its workspace, whatever its permissions. Inviting, changing or removing members, share links (even listing them) and deleting the workspace answer 403 with code: "workspace_scope_mismatch", or key_permission first when a restricted key lacks the level the endpoint needs, as described in What a workspace-scoped key can do. So Settings offers it Members at Read at most, and the API refuses Members write for it with 400 and code: "invalid_permissions".

​
Computers that hold their own key

A computer can hold its own Orgo key, a computer key, such as one that runs your Bops bots. That key has full access to its computer and never expires. Anything that controls the computer can read that key. So a restricted key, or one that expires, can’t control such a computer: the Control and AI endpoints about it (its screen, files, commands, terminal and agent), the Desktop API proxy and its screen password answer 403:
Its Computers endpoints, such as start, stop and get, still work. Use a full access key that never expires for such a computer. Computer keys are described in Key scopes and computer keys.

​
How to read the tables

  • Paths are relative to https://www.orgo.ai. {id} and other braces are path parameters.
  • Workspace paths are written /api/projects/.... /api/workspaces/... is the same endpoint and needs the same permission.
  • HEAD needs what GET needs.
  • WebSocket rows are connections such as wss://www.orgo.ai/desktops/{id}/ws/websockify.
This page lists the 510 endpoints a key may call. Every other endpoint is one of the kinds described in Endpoints a restricted key never uses.

​
Computers group

Records and lifecycle of computers: list and read them; create, delete, start, stop, suspend, resume, resize, copy, back up, restore and move them. 27 read, 43 write.

​
Control group

Using a running computer: screenshots and files on it (read); its live screen, commands, clicks, typing, a terminal, apps and deploys that run on it (write). 28 read, 51 write.

​
Files group

Files stored in Orgo. 4 read, 5 write.

​
Templates group

Templates: read them; publish, build and run previews (write). 13 read, 11 write.

​
Workspaces group

Workspaces: list and read them; create, rename and delete them (write). 23 read, 17 write.

​
Members group

People, invites and share links. 1 read, 9 write.

​
Secrets group

The names of your secrets (read); setting, deleting, applying and using them (write). Revealing a value is never a key’s. Putting them on a computer is write: a key without Secrets write launches a template as if you had saved no secrets (the computer gets none of yours), and can’t ask for Build & launch (403 with code: "key_permission"). 5 read, 7 write.

​
AI group

Models, chats and agents. Write means it may use them. 64 read, 80 write.

​
Bops group

What the Bops app keeps in Orgo: its settings, map, routines, access and Orbit. 19 read, 27 write.

​
Billing group

Plan, credits, usage and invoices (read); anything that buys, changes or cancels (write). 35 read, 33 write.

​
API keys group

Listing keys (read); making, changing and revoking them (write), never past the key’s own access. 3 read, 5 write.

​
Which endpoints a one-computer key can call

A one-computer key reaches a single Linux computer and nothing else. It can call only the endpoints below, and only about its own computer, within its permissions. Anything else answers 403 with code: "computer_scope". How to make one, and what it can never do, is described in One-computer keys for contractors and embeds. A computer’s own key, the one Orgo makes for a computer, calls a different list. It is described in What a computer key can call.

​
Endpoints a restricted key never uses

Every endpoint not listed on this page is one of these kinds. None is in a group, so a restricted key, a one-computer key and a computer’s own key are refused all of them with 403.
  • Only you, signed in. Key security, signing in and out, linking other accounts, and what only a browser does. Some also take a full access key or the key a Bops app signed in with; a restricted key or a computer’s own key never can.
  • Open to anyone. Health and status, sign-in flows, and webhooks that other services send, checked by their signature. They need no key.
  • Orgo staff. Orgo’s own tools. No key of yours reaches them.
  • Orgo’s own machinery. Called by Orgo’s own servers and computers with credentials of their own.
  • Scheduled jobs. Orgo’s own jobs, run on a schedule.