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

# Workspaces

> Switch between workspaces, create additional ones within your plan limit, and invite teammates into each one.

A **workspace** is a fully isolated tenant: its own assistants, calls,
campaigns, knowledge bases, phone numbers, plan, credits, and billing. Signing
up automatically creates one personal workspace with you as its **owner**.
From there you can be invited into other people's workspaces as a **member**
(or **admin**, **viewer**, **billing**), and — within your plan's limit — you
can create additional workspaces of your own.

## Switching workspaces

Click the workspace avatar at the top of the sidebar to open the switcher. It
lists every workspace you belong to, with your role in each one. Selecting a
workspace sets it as active and reloads the app so every server-side route
picks it up immediately. The active workspace only changes for your own
browser session — it never changes what other members of a workspace see.

## Creating an additional workspace

Open the switcher and choose **New workspace** in the footer, or call
`POST /api/workspaces` directly. You become that workspace's **owner** and it
starts with its own (unconfigured) plan and zero balance.

How many additional workspaces you may create is a plan limit,
`max_workspaces`:

* `-1` means unlimited.
* `0` (the default) means the feature is off — you can still be invited into
  other people's workspaces, you just cannot create your own beyond the one
  from sign-up.
* Any other number is the count of workspaces you may create **beyond** your
  first one — so a plan with `max_workspaces: 2` lets you own 3 workspaces in
  total.

Your allowance is the **highest** `max_workspaces` value across every
workspace you already own — owning one workspace on a higher plan raises your
allowance everywhere, even for workspaces you only created later on a lower
plan. If you belong to workspaces only as a member (never as owner), your
allowance is 0: creating a workspace always makes you its owner, so it is
governed by a plan you own, not one you were merely invited into.

Need more than your plan includes? The **extra\_workspaces** add-on (where
enabled on your plan) raises your allowance in tiered steps without changing
your base plan. A platform-admin support override can also raise or lower an
individual account's allowance directly.

Workspace creation is scoped to one brand at a time: on the platform's main
domain you can only create platform workspaces, and on a white-label
reseller's domain you can only create workspaces that belong to that
reseller. Existing workspaces are never suspended or hidden when you are
later at or over your allowance — the limit only blocks creating new ones.

<Note>
  Creating a workspace requires an authenticated, non-suspended account. It
  never depends on your role in whichever workspace happens to be active at the
  time — a `member` in one workspace can still create and own a brand-new one.
</Note>

## Inviting teammates

Each workspace manages its own membership independently under **Settings →
Team**, scoped to whichever workspace is currently active — the panel header
names it, so you always know which workspace an invite lands in. Roles
(`owner`, `admin`, `member`, `viewer`, `billing`) are per-workspace: the same
person can be an owner in one workspace and a read-only viewer in another.

## REST API

```bash theme={null}
curl https://YOUR_DOMAIN/api/v1/workspaces \
  -H "Authorization: Bearer fam_..."
```

```bash theme={null}
curl -X POST https://YOUR_DOMAIN/api/v1/workspaces \
  -H "Authorization: Bearer fam_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"Acme Corp — EU"}'
```

`GET /api/v1/workspaces` lists every workspace visible to the calling
credential: for a user-owned API key or OAuth token, every workspace its
owner belongs to within that key's own brand, with the key's own workspace
flagged `current: true`. A service-account key is a single workspace by
construction and only lists itself.

`POST /api/v1/workspaces` requires a **user-owned** credential — a
service-account key cannot own a workspace and gets `403`. On success it
returns the new workspace with `role: "owner"`. Once the allowance is
exhausted it fails with `403 { error: { code: "forbidden" }, meta: { used,
allowed } }`.

REST scopes are `settings:read` / `settings:write`.

## MCP

* `list_workspaces` — same visibility rules as the REST list endpoint.
* `create_workspace` — same allowance and user-principal requirement as the
  REST create endpoint.

All MCP results use the same public-payload sanitizer as the REST API — a
workspace's internal identifier is exposed only as `id`, never as
`tenant_id`.