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

# Workspace Overview

> Members, roles, invitations, files, preferences, tool accounts, and approval tasks — everything that sits above the individual modules.

## What is a workspace?

A workspace is the top-level container in Connie. Every contact, page, workflow, message, file, and connected account lives inside one. Users can belong to **multiple workspaces** and switch between them from the sidebar.

Each workspace has:

* A UUID `id` and a short URL **slug**
* A display name and (optional) logo
* A subscription plan and credit balance
* A set of **members** with roles
* A **settings** blob — defaults, feature toggles, the workspace invite code

<Info>
  All Connie plans include **unlimited seats** and **unlimited connected accounts**. The only thing that scales with plan size is credit allowance.
</Info>

***

## Roles

Four roles, each with a defined capability ceiling:

| Role | Can do |
| - | - |
| **Owner** | Everything. Only owners can delete the workspace or assign / remove the owner role. |
| **Admin** | Invite & remove members, change member roles (except owner), manage tool accounts, configure settings. |
| **Member** | Use the product. Read/write within the modules they have access to. Cannot manage other members or billing. |
| **Guest** | Limited read/write — typically scoped to specific shared resources (a page, a thread). |

<Note>
  Guest is a **role**, not a separate member type. A guest sits in `workspace_members` like any other user, just with reduced permissions.
</Note>

***

## Adding people

Two flows, both pointed at `workspace_invites`:

<CardGroup cols={2}>
  <Card title="Direct email invite" icon="envelope">
    Admin enters an email → Connie generates a **7-day expiring token** → user accepts at `/invite/{token}`. If the user already exists in Connie, they're added immediately on invite send.
  </Card>

  <Card title="Workspace invite code" icon="key">
    A 12-character, non-expiring, reusable code lives in `settings.invite_code`. Anyone with the code joins via `/invite/{code}`. Used for broad onboarding (e.g. "everyone with this URL can join").
  </Card>
</CardGroup>

Pending invites are listable, resendable, and revocable — see the API reference cards at the bottom.

***

## Page invites vs workspace invites

These are **different flows** that often get confused:

| Surface | What it grants | Token table | Endpoint |
| - | - | - | - |
| **Workspace invite** | Membership in the workspace | `workspace_invites` | `/invites/{token}` |
| **Page invite** | Access to a single page | `page_invites` | `/page-invites/{token}` |

Page invites are emitted from the Pages module's share modal. If a recipient isn't yet a workspace member, accepting a page invite **also adds them as a guest** to the workspace.

***

## Settings

Workspace settings are a JSONB blob editable by admins:

* `logo_url` — uploaded to the `workspace-logos` bucket
* `invite_code` — the reusable invite code
* `default_thread_visibility` — public-to-workspace vs. private-by-default
* `allow_guest_access` — kill switch for the entire guest role
* Module-specific toggles surfaced in **Settings → Workspace**

Logo uploads go to a dedicated endpoint (`uploadWorkspaceLogo`) and write the resulting URL into the settings blob.

***

## Tool accounts

Tool accounts are **per-workspace OAuth-managed connections** — Gmail mailboxes, LinkedIn accounts, Slack workspaces, Stripe organizations, etc.

What makes them workspace-level instead of user-level:

* **Shared across the team** — once an admin connects the workspace's Stripe account, every workflow and every member can use it
* **Access modes** per tool: `auto`, `requires_approval`, or `disabled` — admins control which tools workflows can call without explicit human approval
* **Default account** — for tools that can have multiple accounts (e.g. several mailboxes), one is marked default for unscoped operations

Tool accounts are distinct from the **Tools module** itself — Tools manages the *integration definitions* and connection flow, while workspace tool accounts are the *credentialed instances* that workflows operate on.

***

## Approval tasks

Some workflows pause and require a human to approve before continuing — these surface as **approval tasks** in the workspace.

Lifecycle:

1. A workflow hits a `humanApproval` node (Temporal activity)
2. The dispatcher fans out a notification to every user in `required_approvers`
3. Approvers see the task in the workspace tasks view and can **approve** or **reject**
4. The workflow resumes (on approve) or terminates (on reject)
5. If the task times out (configurable per node), the run is cancelled

Approval tasks link back to the originating workflow run, so you can trace exactly why a task fired. Read state is shared across approvers — once one teammate handles a task, it disappears from everyone's list.

***

## Files

`workspace-files` is a general-purpose file store scoped to your workspace — useful for attachments referenced by workflows, tasks, or shared from chat.

* Multipart upload with signed-URL persistence to Supabase storage
* Paginated list + search by filename
* Download URLs are short-lived signed links — safe to share but they expire
* Admins can delete any file; members can delete their own

***

## Preferences

Three layers of preference, each with its own endpoint:

<CardGroup cols={3}>
  <Card title="User × workspace" icon="user-gear">
    `/user-preferences` — per-user, per-workspace settings: selected inbox accounts, unread-only filter, theme, AI tool category opt-ins, emoji skin tone, reaction shortcuts.
  </Card>

  <Card title="User × global" icon="bell">
    `/user/notification-preferences` — global toggles for the 21 notification categories (email + bell per category). `payment_subscription` is always on and cannot be muted.
  </Card>

  <Card title="Workspace × global" icon="building">
    `/workspaces/{id}/settings` — admin-managed defaults that apply to the entire workspace.
  </Card>
</CardGroup>

***

## Profile

User-level (not workspace-level) endpoints for personal profile management:

* `/profile/avatar` — upload PNG/JPEG/WebP up to 2 MB; stored in `profile-avatars` bucket
* Avatar URLs include a cache-bust timestamp so updates show immediately across all workspaces

***

## Common workflows

### Onboard a new teammate

1. **Settings → Members → Invite** with their email and target role
2. They receive an email with the 7-day token link
3. Once accepted, they appear in the member list and seat-count is reconciled with Stripe automatically

### Set up a shared mailbox the team can run automations against

1. Connect the mailbox via **Tools** as a workspace tool account
2. Admin marks the account as **default** for the email tool
3. Workflows that send email pick this account automatically — no per-flow configuration

### Require approval on outbound messages

1. **Settings → Tool access** → set the email tool to `requires_approval`
2. Add yourself as an approver
3. Any workflow that tries to send an email now creates an approval task — you confirm or reject inline

***

## API reference

<CardGroup cols={2}>
  <Card title="Members" icon="users" href="/api-reference/members/list-members">
    List, invite, update roles, and remove workspace members.
  </Card>

  <Card title="Invitations" icon="envelope-open" href="/api-reference/invitations/list-invitations">
    Manage pending invites — list, resend, revoke, accept, decline.
  </Card>

  <Card title="Page invites" icon="file-export" href="/api-reference/page-invites/get-page-invite">
    Accept or decline a per-page invite token.
  </Card>

  <Card title="Files" icon="folder" href="/api-reference/files/list-workspace-files">
    Workspace-scoped file store with signed-URL upload and download.
  </Card>

  <Card title="Preferences" icon="sliders" href="/api-reference/preferences/get-user-preferences">
    User and workspace preference endpoints.
  </Card>

  <Card title="Tool accounts" icon="plug" href="/api-reference/tool-accounts/list-tool-accounts">
    Manage per-workspace OAuth integration accounts.
  </Card>

  <Card title="Approvals" icon="check" href="/api-reference/approvals/list-approval-tasks">
    Inspect and resolve pending approval tasks.
  </Card>

  <Card title="Settings" icon="gear" href="/api-reference/settings/update-workspace-name">
    Workspace name, logo, and settings JSONB.
  </Card>
</CardGroup>


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