Orgo - Cloud computers for AI agents

All API requests require a Bearer token in the Authorization header.

Authorization: Bearer sk_live_your_api_key_here

Only tokens beginning with sk_ are treated as API keys. Tokens beginning with orgo_mcp_ are issued to MCP clients through the MCP sign-in flow, and reach only computer, file, and workspace-read endpoints. Any other Bearer value is ignored, and the request falls through to browser session authentication. A server-to-server caller has no browser session, so the request fails with 401.

Get your API key

Sign in at orgo.ai/start.
Open orgo.ai/settings/credentials.
In the API keys section, click New key.
Pick a scope (described in Key scopes) and a name, then select Create key.
Copy the plaintext value. It is shown once.

Key scopes

Every API key is either account-wide or pinned to a single workspace.

Scope	What it means
Account-wide	No workspace attached. Reaches everything the account can reach.
Workspace-scoped	One workspace attached. Reaches that workspace and the computers and files in it, and nothing else.

What a workspace-scoped key can do

Scope is checked on every request, before the endpoint runs. A workspace-scoped key:

Can call the computer, workspace, file, and screenshot endpoints, but only for its own workspace and the computers and files in it. Any other workspace ID, computer ID, or file ID is refused.
Sees only its own workspace in List workspaces.
Cannot create workspaces.
Cannot call any other endpoint, including templates, chat completions, and threads.
Can list API keys, filtered to its own workspace, but cannot create or delete keys.

A refused request carries one of these messages:

{ "error": "This API key cannot access this workspace (workspace_scope_mismatch)." }

{ "error": "This endpoint requires an account-wide credential (workspace_scope_mismatch)." }

{ "error": "Workspace-scoped keys cannot create workspaces (workspace_scope_mismatch)." }

The status is 403 on most endpoints. Some endpoints answer every failed access check with 401 instead, with the same body. Each endpoint’s page lists which one it returns. The OpenAI-compatible surface (/v1/...) returns its own 401 envelope, described in the note under Error responses. A few endpoints, such as Upload file, add a second check with a richer body:

{
  "error": "This API key is scoped to workspace <key-workspace>. It cannot access workspace <target>. Use an account-wide key, or create a key scoped to the target workspace.",
  "code": "workspace_scope_mismatch",
  "key_workspace_id": "<key-workspace>",
  "target_workspace_id": "<target>"
}

Match on the workspace_scope_mismatch text, which every variant contains, rather than on the full message.

Workspace roles

The same check applies your role in the workspace, whether you authenticate with a key or a session. An invited member with view-only access can read the workspace and its computers but cannot change them. A write attempt is refused with This workspace is view-only. Ask the owner for write access (workspace_read_only). A workspace you neither own nor belong to is refused with You do not have access to this workspace.

Rotating a key

Generate a new key, update your client to use it, then delete the old one. Both keys work while you migrate. Key list, creation, and deletion live at orgo.ai/settings/credentials. There is no documented public endpoint for managing keys.

Store API keys securely. Never commit them to version control or share them publicly. Rotate immediately if a key is exposed.

Examples

curl https://www.orgo.ai/api/workspaces \
  -H "Authorization: Bearer $ORGO_API_KEY"

import requests
import os

api_key = os.environ["ORGO_API_KEY"]

response = requests.get(
    "https://www.orgo.ai/api/workspaces",
    headers={"Authorization": f"Bearer {api_key}"},
)

const apiKey = process.env.ORGO_API_KEY;

const response = await fetch('https://www.orgo.ai/api/workspaces', {
  headers: { 'Authorization': `Bearer ${apiKey}` },
});

Environment variables

export ORGO_API_KEY=sk_live_abc123

.env

ORGO_API_KEY=sk_live_abc123

Error responses

Status	Body	Meaning
`401`	`{ "error": "Invalid API key" }`	The Bearer token starts with `sk_` but is not a known Orgo key. Check for typos; generate a new one if needed.
`401`	`{ "error": "Authentication required" }`	No `Authorization` header, or a Bearer token that is not an `sk_` key, and no signed-in session.
`401`	`{ "error": "MFA required" }`	The signed-in session has a verified TOTP factor but no valid MFA cookie. Session calls only: API key requests are never MFA-gated.
`401`	`{ "error": "Authentication error" }`	Authentication failed unexpectedly on the server. Retry.
`401` or `403`	`{ "error": "This API key cannot access this workspace (workspace_scope_mismatch)." }`	A workspace-scoped key addressed another workspace, or a computer or file in one.
`401` or `403`	`{ "error": "This endpoint requires an account-wide credential (workspace_scope_mismatch)." }`	A workspace-scoped key called an endpoint outside the computer, workspace, and file surfaces.
`401` or `403`	`{ "error": "You do not have access to this workspace." }`	The key’s account neither owns nor belongs to the target workspace.
`401` or `403`	`{ "error": "This workspace is view-only. Ask the owner for write access (workspace_read_only)." }`	The key’s account has view-only access and the request changes something.
`403`	`{ "error": "…", "code": "workspace_scope_mismatch", "key_workspace_id": "…", "target_workspace_id": "…" }`	A workspace-scoped key acted on another workspace, on an endpoint with the second check.
`403`	`{ "error": "Sign up to create your own workspace.", "code": "GUEST_RESTRICTED" }`	The caller joined through a share link. Guests cannot create workspaces, computers, or invites.
`503`	`{ "error": "Service temporarily unavailable. …" }`	Orgo could not verify the credential because of a server-side fault, such as a database outage. The response carries `Retry-After: 5`. Some endpoints report this as `401` with the same message. Retry either way. Do not rotate the key.

The OpenAI-compatible surface (/v1/chat/completions and /v1/threads) uses a nested error envelope instead: { "error": { "type": "authentication_error", "message": "…", "code": "invalid_api_key" } }. It returns that one body with 401 for every authentication or access failure, including a missing or invalid key and a workspace-scoped key.

See Troubleshooting for the full error reference and recovery steps.

Security tips

Use environment variables. Never hardcode keys.
Add .env to .gitignore.
Create a separate workspace-scoped key per integration, keeping in mind the limits above.
Rotate keys when team members leave.

Need help?

Email spencer@orgo.ai. Include the request_id from the error response when the response carries one.

Overview

Account

Clients

Computer Use API

Workspaces

Computers

Computer Lifecycle

Computer Actions

Screens

Files

Templates

Authentication

Get your API key

Key scopes

What a workspace-scoped key can do

Workspace roles

Rotating a key

Examples

Environment variables

Error responses

Security tips

Need help?

​Get your API key

​Key scopes

​What a workspace-scoped key can do

​Workspace roles

​Rotating a key

​Examples

​Environment variables

​Error responses

​Security tips

​Need help?

Get your API key

Key scopes

What a workspace-scoped key can do

Workspace roles

Rotating a key

Examples

Environment variables

Error responses

Security tips

Need help?