Skip to main content
All API requests require a Bearer token in the Authorization header.
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, and Ask support. Tokens beginning with orgo_vm_ are a computer’s identity tokens, described in Get an identity token inside a computer. 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

  1. Sign in at orgo.ai/start.
  2. Open orgo.ai/api-keys.
  3. Select New key.
  4. Pick a scope (described in Key scopes) and a name, then select Create key.
  5. Copy the plaintext value. It is shown once.
An AI agent with no person present can get its own account and key in one call instead. See Let an agent sign up on its own.

Permissions, expiry and computer keys

A key can be narrower than your account. It can be restricted to some permission groups at read or write, as described in API key permissions. It can expire on a date, as described in Key expiry and rotation. It can reach one workspace or one computer, and Orgo puts a key of its own on some computers, as described in Key scopes and computer keys. Every call that creates, lists, changes or revokes a key, with its errors, is in Create and manage API keys. Soon a program on a Linux computer will also be able to use a short-lived identity token instead of a key, as described in Get an identity token inside a computer.

Key scopes

Every API key is either account-wide or pinned to a single workspace. A key can also be bound to one computer, as described in Key scopes and computer keys.

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.
  • Can call chat completions for computers in its own workspace.
  • Can ask support, which then reads only its own workspace’s computers.
  • Sees only its own workspace in List workspaces.
  • Cannot create workspaces.
  • Cannot manage people or delete its workspace, whatever its permissions. It can list the workspace’s members and open invites, but it cannot invite anyone, revoke an invite, change a role, remove a member or leave, read, make or revoke share links, accept an invite, transfer the workspace or delete it.
  • Cannot call any other endpoint, including templates and threads.
  • Can list, make, change and revoke the API keys of its own workspace, never wider than itself and never a one-computer key, as described in What a workspace key can manage.
  • Is never made with Members write. Making a restricted workspace key with Members write, or changing a key to that, answers 400 with code: "invalid_permissions", whoever asks. Members read or none is fine.
A refused request carries one of these messages:
The status is 403. The OpenAI-compatible surface (/v1/...) puts the same status and message in its own envelope, described in the note under Error responses. A few endpoints, such as Upload file, add a second check with a richer body:
Every variant carries code: "workspace_scope_mismatch". Match on the code rather than on the message. Accepting an invite with a full access workspace key answers 403 with the message Use your signed-in account to accept invitations. A restricted workspace key without Members write gets key_permission first. Transferring a workspace with any key answers 403 with Transfer ownership from the app while signed in.

Workspace roles

The same check applies your role in the workspace, whether you authenticate with a key or a session. An invited member with Can chat access can read the workspace and its computers but cannot change them. A write attempt is refused with 403, code: "workspace_read_only" and 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/api-keys, and also through /api/keys:
Always send a JSON body to POST /api/keys, even {}. A call with no body at all deletes your unnamed account-wide key before it makes the new one.
Store API keys securely. Never commit them to version control or share them publicly. Rotate immediately if a key is exposed.

Examples

Environment variables

.env

Error responses

A 401 with no code, such as the four above, also carries docs in the body, a link to orgo.ai/auth.md that says how to sign in, and a WWW-Authenticate: Bearer realm="Orgo API" header.
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" } }. A missing or invalid key answers that body with 401. Every other refusal keeps the status and message in the tables above, with type set by the status (permission_error for 403, api_error for 503, which also carries Retry-After: 5) and code from the refusal, or invalid_api_key when the refusal has none. For example, a workspace-scoped key on /v1/threads answers 403 with This endpoint requires an account-wide credential (workspace_scope_mismatch).
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 contact@orgo.ai. Include the request_id from the error response when the response carries one.