> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orgo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> API key setup, scopes, and rotation

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

```http theme={null}
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

1. Sign in at [orgo.ai/start](https://www.orgo.ai/start).
2. Open [orgo.ai/settings/credentials](https://www.orgo.ai/settings/credentials).
3. In the **API keys** section, click **New key**.
4. Pick a scope (described in [Key scopes](#key-scopes)) and a name, then select **Create key**.
5. 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](/api-reference/workspaces/list).
* Cannot create workspaces.
* Cannot call any other endpoint, including [templates](/api-reference/templates/schema), [chat completions](/api-reference/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:

```json theme={null}
{ "error": "This API key cannot access this workspace (workspace_scope_mismatch)." }
```

```json theme={null}
{ "error": "This endpoint requires an account-wide credential (workspace_scope_mismatch)." }
```

```json theme={null}
{ "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](#error-responses).

A few endpoints, such as [Upload file](/api-reference/files/upload), add a second check with a richer body:

```json theme={null}
{
  "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](https://www.orgo.ai/settings/credentials). There is no documented public endpoint for managing keys.

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

## Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl https://www.orgo.ai/api/workspaces \
    -H "Authorization: Bearer $ORGO_API_KEY"
  ```

  ```python Python theme={null}
  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}"},
  )
  ```

  ```javascript JavaScript theme={null}
  const apiKey = process.env.ORGO_API_KEY;

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

## Environment variables

```bash theme={null}
export ORGO_API_KEY=sk_live_abc123
```

```bash .env theme={null}
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. |

<Note>
  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.
</Note>

See [Troubleshooting](/guides/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](mailto:spencer@orgo.ai). Include the `request_id` from the error response when the response carries one.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.