Skip to main content

​
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
All Connie plans include unlimited seats and unlimited connected accounts. The only thing that scales with plan size is credit allowance.

​
Roles

Four roles, each with a defined capability ceiling:
Guest is a role, not a separate member type. A guest sits in workspace_members like any other user, just with reduced permissions.

​
Adding people

Two flows, both pointed at workspace_invites:

Direct email invite

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.

Workspace invite code

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”).
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: 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:

User × workspace

/user-preferences — per-user, per-workspace settings: selected inbox accounts, unread-only filter, theme, AI tool category opt-ins, emoji skin tone, reaction shortcuts.

User × global

/user/notification-preferences — global toggles for the 21 notification categories (email + bell per category). payment_subscription is always on and cannot be muted.

Workspace × global

/workspaces/{id}/settings — admin-managed defaults that apply to the entire workspace.

​
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

Members

List, invite, update roles, and remove workspace members.

Invitations

Manage pending invites — list, resend, revoke, accept, decline.

Page invites

Accept or decline a per-page invite token.

Files

Workspace-scoped file store with signed-URL upload and download.

Preferences

User and workspace preference endpoints.

Tool accounts

Manage per-workspace OAuth integration accounts.

Approvals

Inspect and resolve pending approval tasks.

Settings

Workspace name, logo, and settings JSONB.