Organization Management

Multi-tenant organization structure with role-based access control and policy management

Overview

Organizations are the top-level container in Instafill.ai's multi-tenant architecture. An organization holds one or more workspaces, and each workspace's data is isolated by its workspaceId. Organization-level admin operations — such as managing all workspaces, enforcing security policies, or accessing cross-workspace usage reports — require an org-level JWT claim that is distinct from workspace-level membership claims. Standard workspace member tokens carry only workspace-scoped claims and cannot perform organization-level operations even if a user is a member of every workspace in the org.

Cross-workspace sharing of sources and form templates is available at the Enterprise tier. At lower tiers, data remains within the workspace boundary. In all cases, the workspaceId filter applied by the JWT middleware in both the .NET and Python service layers is the enforcement mechanism — it is not possible to bypass it through the API.

Real-World Example: A teleradiology practice automated hospital credentialing by creating one organization with separate workspaces for each hospital network. Organization admins enforced 2FA requirements across all workspaces while each network managed their own credentialing forms.

Organization management provides administrators with tools to invite members, assign org-level roles (Owner, Admin, Member), configure security policies (2FA requirements, session timeouts), set form processing defaults, and manage billing. All workspace activity within the organization is consolidated for reporting and auditing.

Key Capabilities

• Org-Level JWT Claim for Admin Operations: Organization-level administrative actions require an org-level claim in the JWT; workspace-member tokens cannot escalate to org-level operations
• Multiple Workspaces Under One Org: A single billing account covers all workspaces; org admins can create, configure, and delete workspaces without accessing their data
• Cross-Workspace Sharing (Enterprise): Sources and form templates can be shared across workspaces within the same organization; still enforced at the workspaceId boundary per workspace
• Role-Based Access: Owner (full control including deletion), Admin (member management, workspace creation, policy configuration), Member (workspace user — scope limited by workspace role)
• Security Policy Enforcement: Org-level admins configure mandatory 2FA, session timeout policies, and IP restrictions that apply across all workspaces in the org
• Consolidated Usage Reporting: Aggregate quota and request volume across all workspaces for billing and capacity planning
• Member Management: Invite users by email with role assignment; members can be added to individual workspaces after joining the org
• Audit Logging: Org-level actions (member changes, policy updates, workspace creation/deletion) recorded with user, timestamp, and action

How It Works

1. Create Organization:

   • First-time users automatically receive a personal organization
   • Additional organizations can be created for separate business units or clients
   • Organization name and default settings are configured at creation

2. Invite Members:

   • Send email invitations specifying org-level role: Owner, Admin, or Member
   • Accepted invitations result in a JWT that includes the org-level claim at the assigned role
   • Org-level role is separate from workspace role; a user can be an Org Member but a Workspace Admin

3. Configure Policies:

   • Set org-wide security requirements: mandatory 2FA, session timeout duration, IP allowlists
   • Configure form processing defaults applied to new workspaces: AI model preferences, DPI, language
   • Set up webhooks at the organization level for cross-workspace event handling

Real-World Example: Teams using n8n integration configure organization-wide webhooks to trigger automated workflows when forms are completed, sending notifications to Slack or updating CRMs automatically.

4. Create Workspaces:

   • Org Owners and Admins create workspaces from the organization dashboard
   • Each workspace gets its own workspaceId — the data isolation boundary
   • Workspace members are assigned independently of org membership; a user must be an org member before joining a workspace

5. Monitor Activity:

   • Org-level usage dashboard aggregates request volume and quota consumption across all workspaces
   • Audit log records all org-level operations (policy changes, member changes, workspace lifecycle events)
   • Workspace-level logs remain scoped to each workspace and accessible to workspace admins

Real-World Example: Healthcare organizations use team notifications configured at the organization level to alert compliance officers when HIPAA-sensitive forms are completed across any workspace.

Use Cases

Organization management is most useful for companies with multiple distinct business units or client groups that require logical separation. Law firms create separate organizations per practice area — or separate workspaces within one org — so that litigation and real estate teams have isolated form libraries and user access when handling I-485 immigration filings, W-4 onboarding packets, and 1003 mortgage applications respectively. Healthcare systems use a single organization with one workspace per clinic location so that CMS-1500 claims, credentialing forms, and intake documents for each location are never visible to staff at another. Enterprises segment departments to enforce independent quota tracking and billing allocation while keeping all workspaces under one consolidated org account.

Benefits

• Org-Level vs. Workspace-Level Access Separation: Org admins can manage the structure (workspaces, policies, members) without being able to read the form data inside each workspace unless they are also workspace members
• Policy Enforcement at Scale: Setting mandatory 2FA or session timeout at the org level applies the policy to every workspace member without per-workspace configuration
• Enterprise Cross-Workspace Sharing: Sources and form templates can be shared across workspaces within the org at Enterprise tier, reducing duplicate uploads while preserving workspace-level data isolation for sessions and profiles
• Consolidated Billing: One subscription covers all workspaces; usage is aggregated at the org level for quota accounting
• Audit Coverage: Org-level audit log captures the full administrative history — who created workspaces, who changed policies, who was added or removed — separate from the operational activity logs in each workspace

Security & Privacy

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

Org-Level Claim Enforcement: Operations that affect multiple workspaces or org settings require the org-level JWT claim. The service layer checks for this claim before executing org-level operations; a workspace-scoped token cannot perform them regardless of the workspace role it carries.

Role Permissions:

• Owner: Full control including org deletion, billing management, all workspace access
• Admin: Create and delete workspaces, manage org members, configure security policies; cannot delete the organization
• Member: Participate in assigned workspaces at their assigned workspace role; no org-level administrative access

Audit Logging: All org-level changes — member invitations, role changes, workspace creation and deletion, policy updates — are logged with the acting user's identity, timestamp, and the specific change made.

Data Isolation: Organizations are fully isolated from each other; no cross-organization data access is possible. Within an organization, cross-workspace access is limited to org-level admin operations and Enterprise-tier shared resources.

Common Questions