feat(governance): external workspace users from outside org (#4313)

* feat(governance): external workspace users from outside org

* update docs

* address comments

* edge case improvements

* remove unused fallback

* address comments

* add outbox for seat reduction

* fix edge case with org join after invite

* add server side batch invites for workspace

* use zod schema for route

Author: icecrasher321

apps/docs/content/docs/en/credentials/index.mdx

@@ -25,6 +25,8 @@ Secrets are organized into two sections:
 - **Workspace** — shared with all members of your workspace
 - **Personal** — private to you
 
+External workspace members count as workspace members for workspace-scoped secrets. They can use workspace secrets according to their workspace permission level, even though they are not members of your organization.
+
 ### Adding a Secret
 
 Type a key name (e.g. `OPENAI_API_KEY`) into the **Key** column and its value into the **Value** column in the last empty row. A new empty row appears automatically as you type. Existing values are masked by default.
@@ -89,7 +91,7 @@ Click **Save** to apply changes, or **Back** to return to the list.
 
 | | Workspace | Personal |
 |---|---|---|
-| **Visibility** | All workspace members | Only you |
+| **Visibility** | All workspace members, including external workspace members | Only you |
 | **Use in workflows** | Any member can use | Only you can use |
 | **Best for** | Production workflows, shared services | Testing, personal API keys |
 | **Who can edit** | Workspace admins | Only you |

apps/docs/content/docs/en/enterprise/access-control.mdx

@@ -130,6 +130,8 @@ Controls visibility of platform features and modules.
 
 Open the group's **Details** view and add members by searching for users by name or email. Only users who already have workspace-level access can be added. A user can only belong to one group per workspace — adding a user to a new group within the same workspace removes them from their current group for that workspace.
 
+External workspace members are treated like other workspace members for access-control purposes. They can be assigned to permission groups in any workspace they have access to, but they do not become organization members or appear in the organization roster.
+
 ---
 
 ## Enforcement
@@ -159,6 +161,7 @@ When a user opens Mothership, their permission group is read before any block or
 - Moving a user to a new group within a workspace automatically removes them from their previous group in that workspace.
 - Users not assigned to any group in a workspace have no restrictions applied in that workspace (all blocks, providers, and features are available to them there).
 - If **Auto-add new members** is enabled on a group, new members of that workspace are automatically placed in the group. Only one group per workspace can have this setting active.
+- External workspace members follow the same per-workspace permission group rules as internal members.
 
 ---
 

apps/docs/content/docs/en/enterprise/audit-logs.mdx

@@ -44,7 +44,7 @@ Authorization: Bearer <api-key>
 | `resourceType` | string | Filter by resource type (e.g. `workflow`) |
 | `resourceId` | string | Filter by a specific resource ID |
 | `workspaceId` | string | Filter by workspace |
-| `actorId` | string | Filter by user ID (must be an org member) |
+| `actorId` | string | Filter by user ID. For organization-wide filters, the actor must be a current or former org member; workspace-scoped logs can also include external workspace members. |
 | `startDate` | string | ISO 8601 date — return logs on or after this date |
 | `endDate` | string | ISO 8601 date — return logs on or before this date |
 | `includeDeparted` | boolean | Include logs from members who have since left the organization (default `false`) |
@@ -98,6 +98,8 @@ Audit log events follow a `resource.action` naming pattern. The table below list
 | **Credentials** | `credential.created`, `credential.deleted`, `oauth.disconnected` |
 | **Organization** | `organization.updated`, `org_member.added`, `org_member.role_changed` |
 
+Workspace invitation events include whether the invite is for an internal organization member or an external workspace member in their metadata. External workspace members can appear as actors on workspace-scoped events, but they are not organization members and do not appear in the organization roster.
+
 ---
 
 <FAQ items={[
@@ -123,7 +125,7 @@ Audit log events follow a `resource.action` naming pattern. The table below list
   },
   {
     question: "Can I filter logs by a specific user?",
-    answer: "Yes. Pass the actorId query parameter to filter logs by a specific user. The actor must be a current or former member of your organization."
+    answer: "Yes. Pass the actorId query parameter to filter logs by a specific user. Organization-wide actor filters require the actor to be a current or former member of your organization. Workspace-scoped logs may also include external workspace members who acted inside a workspace without joining the organization."
   }
 ]} />
 

apps/docs/content/docs/en/enterprise/index.mdx

@@ -13,6 +13,8 @@ Sim Enterprise provides advanced features for organizations with enhanced securi
 
 Define permission groups on a workspace to control what features and integrations its members can use. Permission groups are scoped to a single workspace — a user can belong to different groups (or no group) in different workspaces.
 
+External workspace members can be assigned to permission groups just like internal organization members, but they remain outside the organization roster and do not consume seats.
+
 ### Features
 
 - **Allowed Model Providers** - Restrict which AI providers users can access (OpenAI, Anthropic, Google, etc.)
@@ -81,4 +83,4 @@ Self-hosted deployments enable enterprise features via environment variables ins
 | `INBOX_ENABLED`, `NEXT_PUBLIC_INBOX_ENABLED` | Sim Mailer inbox |
 | `DISABLE_INVITATIONS`, `NEXT_PUBLIC_DISABLE_INVITATIONS` | Disable invitations; manage membership via Admin API |
 
-Once enabled, each feature is configured through the same Settings UI as Sim Cloud. When invitations are disabled, use the Admin API (`x-admin-key` header) to manage organization and workspace membership.
+Once enabled, each feature is configured through the same Settings UI as Sim Cloud. When invitations are disabled, use the Admin API (`x-admin-key` header) to manage organization membership and workspace access. Internal members join the organization; external workspace members only receive access to a specific workspace.

apps/docs/content/docs/en/enterprise/sso.mdx

@@ -221,6 +221,8 @@ Once SSO is configured, users with your domain (`company.com`) can sign in throu
 
 Users who sign in via SSO for the first time are automatically provisioned and added to your organization — no manual invite required.
 
+SSO provisioning creates internal organization members. External workspace members are different: they are invited to a specific workspace without joining your organization or consuming one of your seats.
+
 <Callout type="info">
   Password-based login remains available. Forcing all organization members to use SSO exclusively is not yet supported.
 </Callout>
@@ -242,7 +244,7 @@ Users who sign in via SSO for the first time are automatically provisioned and a
   },
   {
     question: "What happens when a user signs in with SSO for the first time?",
-    answer: "Sim creates an account for them automatically and adds them to your organization. No manual invite is needed. They are assigned the member role by default."
+    answer: "Sim creates an account for them automatically and adds them to your organization. No manual invite is needed. They are assigned the member role by default. External workspace members are not provisioned through SSO into your organization; they are invited directly to a workspace and remain outside your org roster."
   },
   {
     question: "Can I still use email/password login after enabling SSO?",

apps/docs/content/docs/en/execution/costs.mdx

@@ -272,6 +272,8 @@ Sim has two paid plan tiers - **Pro** and **Max**. Either can be used individual
 
 To use Pro or Max with a team, select **Get For Team** in subscription settings and choose the tier and number of seats. Credits are pooled across the organization at the per-seat rate (e.g. Max for Teams with 3 seats = 75,000 credits/mo pooled).
 
+Internal organization members use seats and contribute to the team's pooled credit allocation. External workspace members do not join your organization, do not appear in the organization roster, and do not count toward your seat total.
+
 ### Daily Refresh Credits
 
 Paid plans include a small daily credit allowance that does not count toward your plan limit. Each day, usage up to the daily refresh amount is excluded from billable usage. This allowance resets every 24 hours and does not carry over - use it or lose it.
@@ -317,7 +319,7 @@ By default, your usage is capped at the credits included in your plan. To allow
 | **Max** | Up to 10 | — |
 | **Team / Enterprise** | Unlimited | Unlimited |
 
-Team and Enterprise plans unlock shared workspaces that belong to your organization. Members invited to a shared workspace automatically join the organization and count toward your seat total. When a Team or Enterprise subscription is cancelled or downgraded, existing shared workspaces remain accessible to current members but new invites are disabled until the organization is upgraded again.
+Team and Enterprise plans unlock shared workspaces that belong to your organization. Internal members invited to a shared workspace join the organization and count toward your seat total. Existing Sim users who already belong to another organization can be added as external workspace members; they get workspace access without joining your organization or using one of your seats. When a Team or Enterprise subscription is cancelled or downgraded, existing shared workspaces remain accessible to current members but new invites are disabled until the organization is upgraded again.
 
 ### Rate Limits
 
@@ -368,7 +370,8 @@ Sim uses a **base subscription + overage** billing model:
 - Example: 7,000 credits used = $25 (subscription) + $5 (overage for 1,000 extra credits at $0.005/credit)
 
 **Team Plans:**
-- Usage is pooled across all team members in the organization
+- Usage is pooled across internal team members in the organization
+- External workspace members keep their own organization or personal billing context for runs where they are the billing actor
 - Overage is calculated from total team usage against the pooled limit
 - Organization owner receives one bill
 

apps/docs/content/docs/en/mailer/index.mdx

@@ -42,6 +42,8 @@ Only authorized senders can create tasks. Emails from anyone else are automatica
 - **Workspace members** are allowed by default — no setup needed
 - **External senders** can be added manually with an optional label for easy identification
 
+External senders are email addresses that can create inbox tasks. They are not the same as external workspace members, who have workspace access in Sim without joining your organization.
+
 Manage your allowed senders list in **Settings** → **Inbox** → **Allowed Senders**.
 
 ## Tracking Tasks

apps/docs/content/docs/en/permissions/roles-and-permissions.mdx

@@ -12,7 +12,7 @@ When you invite team members to your organization or workspace, you'll need to c
 Sim has two kinds of workspaces:
 
 - **Personal workspaces** live under your individual account. The number you can create depends on your plan.
-- **Shared (organization) workspaces** live under an organization and are available on Team and Enterprise plans. Any organization Owner or Admin can create them. Members invited to a shared workspace automatically join the organization and count toward your seat total.
+- **Shared (organization) workspaces** live under an organization and are available on Team and Enterprise plans. Any organization Owner or Admin can create them. Internal members invited to a shared workspace join the organization and count toward your seat total. Existing Sim users who already belong to another organization can be added as external workspace members instead, giving them access to the workspace without adding them to your organization roster or using one of your seats.
 
 ### Workspace Limits by Plan
 
@@ -43,6 +43,15 @@ When inviting someone to a workspace, you can assign one of three permission lev
 | **Write** | Create and edit workflows, run workflows, manage environment variables |
 | **Admin** | Everything Write can do, plus invite/remove users and manage workspace settings |
 
+## Internal Members vs External Workspace Members
+
+Workspace permissions are separate from organization membership:
+
+- **Internal organization members** belong to your organization, appear in the organization roster, and count toward your seat total. Invite new teammates this way when they should be part of your company or team in Sim.
+- **External workspace members** have access only to the workspace they are invited to. They keep their own organization membership, do not appear in your organization roster, and do not count toward your organization's seats. Use external access for clients, partners, contractors, or collaborators who already use Sim in another organization.
+
+External workspace members still receive a workspace permission level — Read, Write, or Admin — and that permission controls what they can do inside the workspace.
+
 ## What Each Permission Level Can Do
 
 Here's a detailed breakdown of what users can do with each permission level:
@@ -126,7 +135,7 @@ Every workspace has one **Owner** (the person who created it) plus any number of
 2. **Workspace level**: Give them **Admin** permission so they can manage the team and see everything
 
 ### Adding a Stakeholder or Client
-1. **Organization level**: Invite them as an **Organization Member**
+1. **Organization level**: If they should not join your organization, add them as an **External workspace member**
 2. **Workspace level**: Give them **Read** permission so they can see progress but not make changes
 
 ---
@@ -199,12 +208,12 @@ An organization has three roles: **Owner**, **Admin**, and **Member**.
 import { FAQ } from '@/components/ui/faq'
 
 <FAQ items={[
-  { question: "What is the difference between organization roles and workspace permissions?", answer: "Organization roles (Owner, Admin, or Member) control who can manage the organization itself, including inviting people, creating shared workspaces, and handling billing. Workspace permissions (Read, Write, Admin) control what a user can do within a specific workspace, such as viewing, editing, or managing workflows. A user needs both an organization role and a workspace permission to work within a shared workspace." },
+  { question: "What is the difference between organization roles and workspace permissions?", answer: "Organization roles (Owner, Admin, or Member) control who can manage the organization itself, including inviting people, creating shared workspaces, and handling billing. Workspace permissions (Read, Write, Admin) control what a user can do within a specific workspace, such as viewing, editing, or managing workflows. Internal members need both an organization role and a workspace permission to work within a shared workspace. External workspace members do not have an organization role in your org; they only have workspace-level access." },
   { question: "How many workspaces can I create?", answer: "Free users get 1 personal workspace. Pro users get up to 3 personal workspaces. Max users get up to 10 personal workspaces. Team and Enterprise plans support unlimited shared workspaces under the organization — new invites are gated by your seat count." },
   { question: "What happens to my shared workspaces if I cancel or downgrade my Team plan?", answer: "Existing shared workspaces remain accessible to current members, but new invitations are disabled until you upgrade back to a Team or Enterprise plan. No workspaces or members are deleted — the organization is simply dormant until billing is re-enabled." },
   { question: "Can I restrict which integrations or model providers a team member can use?", answer: "Yes, on Enterprise-entitled workspaces. Any workspace admin can create permission groups with fine-grained controls, including restricting allowed integrations and allowed model providers to specific lists. You can also disable access to MCP tools, custom tools, skills, and various platform features like the knowledge base, API keys, or Copilot on a per-group basis. Permission groups are scoped per workspace — a user can belong to different groups in different workspaces." },
   { question: "What happens when a personal environment variable has the same name as a workspace variable?", answer: "The personal environment variable takes priority. When a workflow runs, if both a personal and workspace variable share the same name, the personal value is used. This allows individual users to override shared workspace configuration when needed." },
   { question: "Can an Admin remove the workspace owner?", answer: "No. The workspace owner cannot be removed from the workspace by anyone. Only the workspace owner can delete the workspace or transfer ownership to another user. Admins can do everything else, including inviting and removing other users and managing workspace settings." },
   { question: "What are permission groups and how do they work?", answer: "Permission groups are an Enterprise access control feature that lets workspace admins define granular restrictions beyond the standard Read/Write/Admin roles. Groups are scoped to a single workspace: each user can be in at most one group per workspace, and a user can be in different groups across different workspaces. A permission group can hide UI sections (like trace spans, knowledge base, API keys, or deployment options), disable features (MCP tools, custom tools, skills, invitations), and restrict which integrations and model providers its members can access. Members can be assigned manually, and new members can be auto-added on join. Execution-time enforcement is based on the workflow's workspace, not the user's current UI context." },
-  { question: "How should I set up permissions for a new team member?", answer: "Start with the lowest permission level they need. Invite them to the organization as a Member, then add them to the relevant workspace with Read permission if they only need visibility, Write if they need to create and run workflows, or Admin if they need to manage the workspace and its users. You can always increase permissions later." },
+  { question: "How should I set up permissions for a new team member?", answer: "Start with the lowest permission level they need. Invite teammates to the organization as Members, then add them to the relevant workspace with Read permission if they only need visibility, Write if they need to create and run workflows, or Admin if they need to manage the workspace and its users. For clients, partners, or users who already belong to another Sim organization, use external workspace access so they can collaborate without joining your organization or consuming a seat." },
 ]} />

apps/docs/content/docs/en/quick-reference/index.mdx

@@ -31,7 +31,7 @@ A quick lookup for everyday actions in the Sim workflow editor. For keyboard sho
     </tr>
     <tr>
       <td>Invite team members</td>
-      <td>Sidebar → **Invite**</td>
+      <td>Sidebar → **Invite**. Internal invites join the organization; external workspace members get workspace access only.</td>
       <td><ActionVideo src="quick-reference/invite.mp4" alt="Invite team members" /></td>
     </tr>
     <tr>

apps/docs/content/docs/en/triggers/index.mdx

@@ -89,6 +89,8 @@ Polling Groups let you monitor multiple team members' Gmail or Outlook inboxes w
 
 Invitees receive an email with a link to connect their account. Once connected, their inbox is automatically included in the polling group. Invitees don't need to be members of your Sim organization.
 
+This is separate from external workspace membership: polling group invitees are granting access to an inbox for a trigger, while external workspace members are collaborators with Read, Write, or Admin access to a workspace.
+
 **Using in a Workflow**
 
 When configuring an email trigger, select your polling group from the credentials dropdown instead of an individual account. The system creates webhooks for each member and routes all emails through your workflow.