Workspaces and projects

Fillo has two levels on purpose:

• A workspace is the team and billing account. Membership, roles, plan, aggregate usage, and storage connections belong here.
• A project is one site, app, customer deployment, or environment inside that workspace. Forms, responses, respondents, publishable keys, allowed origins, identity secrets, scoped API keys, CLI handoffs, and MCP grants are isolated here.

Every workspace starts with a default project, so existing integrations keep working after the project model is introduced. Creating another project does not create another subscription or reset the workspace's response allowance.

Choose the boundary

Use projects for marketing.example.com and app.example.com, separate client sites, or production and staging when the same Fillo team and bill should own them. Each project gets its own pk_ key and origin allowlist. A key or agent credential for one project cannot enumerate forms or responses in another.

Use separate workspaces only when the team, bill, storage credentials, and administrative ownership must also be separate. A user may still belong to several workspaces by invitation and switch between them.

Create and switch projects

Open the project menu below the workspace menu and choose Create project. Creating a project selects it immediately. The same choice is available while approving a CLI login or remote MCP connection, so the grant can be pinned to the correct site before approval.

Project switching changes the dashboard's active project after checking that the project belongs to the active workspace. Workspace members initially have access to all projects; project-specific member roles are not a separate RBAC layer.

CLI selection

An ordinary human-approved CLI login can manage projects inside its fixed workspace:

fillo project list
fillo project create "Customer site"
fillo project select customer-site-a1b2c3
fillo whoami --json

create and select retarget that login and save the selected project's public pk_ key. Later CLI commands use the selection until it changes. Exact names work only when unique; ids and slugs are unambiguous.

A handoff token is intentionally narrower: it stays pinned to the project a human approved and cannot list, create, or select siblings. The local stdio MCP server always lists the equivalent fillo_list_projects, fillo_create_project, and fillo_select_project tools so an agent can discover the workflow. Calls succeed only when an ordinary CLI login is available; otherwise they return the login step. Hosted remote MCP OAuth grants stay pinned; reconnect and consent for another project.

Keys, origins, and identity

• Each project has one public pk_ publishable key and its own browser-origin allowlist.
• identify() verification uses a project-specific identity secret, so the same external user id can have independent profiles in two projects.
• fsk_ API keys, fsync_ schema tokens, CLI handoffs, and MCP grants carry a project id. They cannot be widened by supplying another form id.
• Webhooks and response destinations are configured per form, and therefore inherit that form's project boundary.

Integration accounts

OAuth connections for Notion, Slack, and HubSpot are reusable assets owned by the workspace. A workspace may connect several accounts for the same provider. Each project explicitly selects one default provider account, and each enabled form pins the exact connection it was configured with. That supports both:

• the same HubSpot account reused by several projects; and
• HubSpot account A for one project and account B for another.

Changing a project's default does not silently retarget existing form destinations. Reconfigure a form to move it. Removing a provider from a project deletes only that project's destinations pinned to the selected account while retaining the reusable credential for sibling projects. Legacy destinations that predate account pinning stay configured but pause until the project selects an account again. Removing the reusable account itself is a separate confirmed workspace action; it deletes every Fillo destination pinned to that account but leaves provider-side channels, databases, and CRM records in place.

Google Drive, Box, and S3-compatible file storage remain workspace-level in the current model. Google Sheets reuses the workspace's Drive connection. Storage usage and file lifecycle therefore remain one shared operational boundary.

Members and roles

Owners and admins invite teammates in Settings > Members. Only the invited email account can accept an invitation.

An admin cannot create, remove, or demote an owner, and no one can remove the last owner. The server rechecks the active workspace, project relationship, and membership for management actions instead of trusting ids from the browser.

Billing and limits

The plan lives on the workspace. Response counts, unclaimed-preview caps, and other usage limits aggregate across all of its projects. Projects are isolation containers, not a way to multiply free allowances. A workspace can currently contain up to 100 projects. Project deletion will ship with explicit cleanup for provider-owned resources; until then, create a separate workspace if that cap is not sufficient. Workspace deletion retains its existing owner-only, 21-day-grace behavior and covers every project below it.

Related

• Security and boundaries: Choose the right credential for each environment.
• CLI and publishing: Stage code-defined schema changes with trusted credentials.
• MCP server: Understand local project selection and remote grant pinning.
• Data retention and deletion: Understand owner-only workspace deletion.