Workspace Management

Isolated workspaces for teams with role-based permissions and custom settings

Overview

workspaceId is the primary data isolation boundary in Instafill.ai. Every object in the system — form sessions, form templates, source documents, profiles, folders, and API keys — is tagged with a workspaceId at creation. All service-layer queries include a workspaceId filter, and the JWT middleware running in both the .NET and Python service layers extracts the workspaceId claim from the request token and applies it to every database query. There is no application-level path that crosses workspace boundaries.

Workspaces exist within organizations and represent the working environment for a team, project, department, or client. Members can belong to multiple workspaces with different roles in each. The isolation guarantee means that a user in Workspace A with no membership in Workspace B cannot enumerate, read, or modify any object owned by Workspace B — even if they are in the same organization.

Real-World Example: A teleradiology practice automated hospital credentialing using separate workspaces for each hospital network. Each workspace maintained its own physician profiles and credentialing forms, ensuring complete data isolation between competing hospital systems.

Workspace isolation ensures that Team A cannot see Team B's forms or data, even within the same organization. This is crucial for law firms (different client matters), healthcare (different departments), or agencies (different clients).

Key Capabilities

• workspaceId as Isolation Boundary: Sessions, forms, sources, profiles, folders, and API keys are all scoped to a workspaceId; the JWT middleware in both .NET and Python services enforces this on every request
• Four Workspace Roles: Owner, Admin, Member, and Viewer (read-only) — each with distinct permissions enforced at the service layer
• Multi-Workspace Membership: A single user account can belong to multiple workspaces with different roles in each, switching context without a separate login
• Per-Workspace Settings: Configure DPI, date formats, language, and file cleanup policies independently per workspace
• Folder Organization: Hierarchical folder structure for organizing forms within the workspace
• Usage Tracking: Workspace-specific quota consumption tracked separately for capacity planning and billing allocation
• Audit Logging: Workspace-level activity records for compliance review

Real-World Example: Legal firms using email automation create separate workspaces per practice area. When attorneys receive case documents via email, they're automatically routed to the correct workspace and stored in organized folders.

Real-World Example: Organizations using team notifications configure different Slack channels per workspace, ensuring the right team gets notified when forms in their workspace are completed.

How It Works

Workspace Roles and Permissions:

Roles are stored as claims in the user's JWT and validated by the service layer on every request. A Viewer role cannot create or modify objects regardless of what the API call requests.

Workspace Isolation in Practice:

When a request arrives at either the .NET or Python service, the JWT middleware:

1. Validates the token signature via JwtKeyManager.cs-compatible verification
2. Extracts the workspaceId claim from the token
3. Injects the workspaceId as a mandatory filter on all subsequent database queries in that request

A user presenting a valid JWT for Workspace A cannot retrieve objects from Workspace B — the workspaceId filter prevents it at the query level, not at a presentation layer.

Creating and Configuring Workspaces:

1. Organization owners and admins create workspaces from the organization dashboard
2. Set workspace name, default DPI, date format, language, and file cleanup policy
3. Invite members by email or assign existing organization members; specify role at assignment
4. Members receive access immediately — their next JWT includes the new workspace in their membership claims

Switching Between Workspaces:

Users with multiple workspace memberships switch via the workspace selector in the navigation header. Switching reissues a context-scoped view within the same session — the workspaceId in play changes to match the selected workspace, and all data shown reflects only that workspace's objects.

Use Cases

Workspace management is most useful wherever distinct teams must work in the same account without seeing each other's data. A law firm handling immigration, employment, and real estate matters creates one workspace per practice area — the litigation team filling I-485 and I-9 forms never sees the real estate team's 1003 mortgage applications. A healthcare system assigns each clinic location its own workspace so that credentialing forms, CMS-1500 claims, and patient intake data for one clinic are never visible to staff at another. Agencies managing multiple client accounts give each client an isolated workspace so that a team member working on Client A cannot browse Client B's form templates or session history.

Benefits

• Hard Data Isolation: The workspaceId filter is applied at the database query level in both service layers — isolation is enforced by the infrastructure, not by UI convention
• Role Granularity: Viewer access lets stakeholders review completed forms without the ability to modify sessions or templates; Admin access lets team leads manage membership without full Owner privileges
• Flexible Membership: A consultant can be a Member in a client workspace and an Owner in their own workspace — the same account, different roles, enforced separately per workspace
• Independent Configuration: Each workspace controls its own DPI, language, and cleanup policies, so teams with different form types (e.g., medical vs. financial) configure their environment without affecting others
• Shared Resources Within Workspace: Profiles and source documents uploaded by any workspace member are accessible to all members with appropriate roles, eliminating duplicate uploads

Security & Privacy

Data is scoped to workspaceId and protected via the shared JWT authentication middleware running in both the .NET and Python service layers.

All service-layer queries include a mandatory workspaceId filter derived from the authenticated token. No service endpoint returns data across workspace boundaries. Members removed from a workspace lose access on their next request — there is no grace period for data access after membership is revoked.

Workspace audit logs record member additions and removals, role changes, settings modifications, and data operations, with the acting user and timestamp for each event.