Authorization header.
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
- Sign in at orgo.ai/start.
- Open orgo.ai/api-keys.
- Select New key.
- Pick a scope (described in Key scopes) and a name, then select Create key.
- Copy the plaintext value. It is shown once.
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
400withcode: "invalid_permissions", whoever asks. Members read or none is fine.
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:
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 with403, 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:
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).Security tips
- Use environment variables. Never hardcode keys.
- Add
.envto.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 therequest_id from the error response when the response carries one.