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

# Workspaces & Teams

> Invite teammates into your Appeeky account, give each one a role, and switch between workspaces in the dashboard, API and MCP.

A **workspace** is an Appeeky account that other people can join. Every account has its own workspace. When you invite teammates, they work inside your workspace with your apps, keywords, competitors, reports and agents. Their usage counts against your plan.

> [!NOTE]
>
> Inviting teammates requires a paid web plan (Indie Dev, Startup or Agentic Scale). Manage your team in **Settings → Team**.

***

## How it works

* **Owner.** You own your workspace. Everything in it is your data: apps, tracked keywords, connected stores, co-founder, reports, balance and plan.
* **Members.** A teammate you invite joins your workspace with a role. They keep their own account and their own workspace as well.
* **Switching.** Members switch between workspaces they belong to. While a workspace is active, everything they do reads and writes the owner's data and uses the owner's plan.

***

## Invite a teammate

1. Open **Settings → Team**.
2. Under **Invite teammates**, enter their email and pick a role.
3. Optionally limit them to specific apps (see [App access](#app-access)).
4. Send the invite. They get an email with a link.
5. They open the link and sign in **with the invited email address**. A different address, such as an Apple private relay address, won't match; invite that address instead.

| Rule | Limit |
| - | - |
| Seats on paid plans | 5, including the owner and pending invites |
| Seats on the free plan | 1 (no invites) |
| Invite expires after | 7 days |
| Invites per workspace | 10 per hour |

Sending a new invite to the same email replaces the earlier one. You can revoke a pending invite from **Pending invites**.

***

## Roles

| Role | Can do |
| - | - |
| **Owner** | Everything, including billing, plan, API keys and the prepaid balance |
| **Admin** | Everything an editor can, plus invite and manage members, store credentials, ad and social account connections, and co-founder integrations |
| **Editor** | Add apps, track keywords, run agents, create content and make other changes |
| **Viewer** | Read-only access |

* Only the owner can invite or promote **admins**. Admins can manage editors and viewers.
* Owners and admins can change roles, remove members and see the **Activity** log of membership changes in **Settings → Team**.
* A member can leave a workspace at any time from **Settings → Team → Leave workspace**.

### App access

An owner or admin can limit a member to some of the workspace's apps. That member:

* only sees data for those apps,
* gets an error when a request names any other app,
* can't use account-wide features with no app attached, such as billing, API keys, store credentials, connected social accounts, the co-founder and usage.

### When the owner's plan ends

If the owner's paid plan becomes inactive, every member's seat is **suspended**. Suspended members can still see the workspace in their list but can't open it. Seats come back as soon as the owner's plan is active again.

***

## Switch workspace

**Dashboard.** Use the workspace switcher at the top of the sidebar. Your own workspace is always listed first.

**API.** Send `X-Workspace-Id` with the workspace id:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl https://api.appeeky.com/v1/user/apps \
  -H "X-API-Key: $APPEEKY_API_KEY" \
  -H "X-Workspace-Id: 3f8c2a10-5b7d-4e2a-9c61-0d4b7e9a1f22"
```

* Use **your own** API key. With the header, the request runs as the workspace owner and uses the owner's plan and credits.
* Without the header, requests run in your own account.
* Responses include `X-Workspace-Id` and `X-Workspace-Role` so you can confirm where you are acting.

**MCP.** Call `team_workspace_list`, then `team_workspace_use` with the id. Clients that let you set HTTP headers can send `X-Workspace-Id` on the MCP connection instead.

***

## API

| Method | Endpoint | Description |
| - | - | - |
| GET | `/v1/workspaces` | Workspaces you belong to and which one is active |

Uses 0 API credits. This endpoint always answers for **you**, even if your `X-Workspace-Id` header points at a workspace you can no longer use, so you can always recover.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "data": {
    "workspaces": [
      {
        "id": "9a0e4c3b-1f2d-4b7a-8e65-6c2d1b0f9e11",
        "name": "My workspace",
        "ownerEmail": "you@example.com",
        "role": "owner",
        "status": "active",
        "isOwn": true,
        "appScope": null
      },
      {
        "id": "3f8c2a10-5b7d-4e2a-9c61-0d4b7e9a1f22",
        "name": "Acme Apps",
        "ownerEmail": "founder@example.com",
        "role": "editor",
        "status": "active",
        "isOwn": false,
        "appScope": null
      }
    ],
    "active": {
      "workspaceId": "3f8c2a10-5b7d-4e2a-9c61-0d4b7e9a1f22",
      "name": "Acme Apps",
      "ownerEmail": "founder@example.com",
      "role": "editor",
      "isDelegated": true,
      "appScope": null
    },
    "requestedWorkspaceError": null
  }
}
```

| Field | Description |
| - | - |
| `role` | Your role: `owner`, `admin`, `editor` or `viewer` |
| `status` | `active` or `suspended` |
| `appScope` | Ids of the apps you're limited to, or `null` for all apps |
| `active` | The workspace your `X-Workspace-Id` resolves to; your own workspace without the header |
| `requestedWorkspaceError` | Set when the header points at a workspace you can't use |

### Errors

| Code | Status | Meaning |
| - | - | - |
| `WORKSPACE_INVALID` | 400 | `X-Workspace-Id` is not a valid id |
| `WORKSPACE_FORBIDDEN` | 403 | You're not a member of this workspace |
| `WORKSPACE_SEAT_SUSPENDED` | 403 | Your seat is suspended because the owner's plan is inactive |
| `WORKSPACE_ROLE_REQUIRED` | 403 | Your role is too low for this action |
| `WORKSPACE_APP_FORBIDDEN` | 403 | You're limited to specific apps and this isn't one of them |
| `WORKSPACE_APP_SCOPE_REQUIRED` | 403 | You're limited to specific apps and this feature is account-wide |

Device push tokens and notification preferences always stay personal: the header is ignored for them.

***

## MCP tools

| Tool | Description |
| - | - |
| `team_workspace_list` | List your workspaces and the one this session acts in |
| `team_workspace_use` | Switch this session to a workspace (`workspace_id`). Omit it, or pass `own`, to go back to your own account. The choice is remembered for about 12 hours |

After switching, every data tool (my apps, keywords, co-founder, connections and so on) works on the selected workspace.

***

## Workspace library (co-founder documents)

The `workspace_*` MCP tools are a different thing: they manage the **co-founder's document library**, where business context, research notes and decision records are kept as markdown files. They work inside whichever team workspace is active.

| Tool | Description |
| - | - |
| `workspace_search` | Search documents by meaning; returns snippets |
| `workspace_list` | List documents with path, department and last update, without content |
| `workspace_read` | Read one document in full by path, with recent revisions |
| `workspace_write` | Create or replace a document. The previous version is kept as a revision |
| `workspace_delete` | Permanently delete a document and its revisions |

These tools use 0 API credits. `business_context.md` and `AGENTS.md` are your own documents: `workspace_write` only overwrites them when `confirm_owner_document` is `true`.

***

## Related

* [Prepaid Balance](https://docs.appeeky.com/docs/wallet.md): who pays in a team
* [Rate Limits & Credits](https://docs.appeeky.com/docs/rate-limits.md): plan credits shared by the team
* [Authentication](https://docs.appeeky.com/docs/authentication.md)


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