improvement(access-control): migrate to workspace scope (#4244)

* improvement(access-control): migrate to workspace scope

* fix edge cases

* update docs

* prep merge

* regen migrations

* address comments

* add ws id, user constraint

* address more comments

* address ui comments

* address more comments

Author: icecrasher321

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

@@ -7,13 +7,13 @@ import { Callout } from 'fumadocs-ui/components/callout'
 import { FAQ } from '@/components/ui/faq'
 import { Image } from '@/components/ui/image'
 
-Access Control lets organization admins define permission groups that restrict what each set of users can do — which AI model providers they can use, which workflow blocks they can place, and which platform features are visible to them. Restrictions are enforced both in the workflow executor and in Mothership.
+Access Control lets workspace admins define permission groups that restrict what each set of workspace members can do — which AI model providers they can use, which workflow blocks they can place, and which platform features are visible to them. Permission groups are scoped to a single workspace: a user can be in different groups (or no group) in different workspaces. Restrictions are enforced both in the workflow executor and in Mothership, based on the workflow's workspace.
 
 ---
 
 ## How it works
 
-Access control is built around **permission groups**. Each group has a name, an optional description, and a configuration that defines what its members can and cannot do. A user can belong to at most one permission group at a time.
+Access control is built around **permission groups**. Each group belongs to a specific workspace and has a name, an optional description, and a configuration that defines what its members can and cannot do. A user can belong to at most one permission group **per workspace**, but can belong to different groups in different workspaces.
 
 When a user runs a workflow or uses Mothership, Sim reads their group's configuration and applies it:
 
@@ -26,13 +26,13 @@ When a user runs a workflow or uses Mothership, Sim reads their group's configur
 
 ### 1. Open Access Control settings
 
-Go to **Settings → Enterprise → Access Control** in your workspace.
+Go to **Settings → Enterprise → Access Control** in the workspace you want to manage. Each workspace has its own set of permission groups.
 
 <Image src="/static/enterprise/access-control-groups.png" alt="Access Control settings showing a list of permission groups: Contractors, Sales, Engineering, and Marketing, each with Details and Delete actions" width={900} height={500} />
 
 ### 2. Create a permission group
 
-Click **+ Create** and enter a name (required) and optional description. You can also enable **Auto-add new members** — when active, any new member who joins the organization is automatically added to this group. Only one group per organization can have this setting enabled at a time.
+Click **+ Create** and enter a name (required) and optional description. You can also enable **Auto-add new members** — when active, any new member who joins this workspace is automatically added to this group. Only one group per workspace can have this setting enabled at a time.
 
 ### 3. Configure permissions
 
@@ -128,7 +128,7 @@ Controls visibility of platform features and modules.
 
 ### 4. Add members
 
-Open the group's **Details** view and add members by searching for users by name or email. Users can only belong to one group at a time — adding a user to a new group removes them from their current one.
+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.
 
 ---
 
@@ -155,41 +155,41 @@ When a user opens Mothership, their permission group is read before any block or
 
 ## User membership rules
 
-- A user can belong to **at most one** permission group at a time.
-- Moving a user to a new group automatically removes them from their current group.
-- Users not assigned to any group have no restrictions applied (all blocks, providers, and features are available to them).
-- If **Auto-add new members** is enabled on a group, new organization members are automatically placed in that group. Only one group per organization can have this setting active.
+- A user can belong to **at most one** permission group **per workspace**, but may be in different groups across different workspaces.
+- 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.
 
 ---
 
 <FAQ items={[
   {
     question: "Who can create and manage permission groups?",
-    answer: "Organization owners and admins can create, edit, and delete permission groups. On Sim Cloud, you must be on the Enterprise plan."
+    answer: "Any workspace admin on an Enterprise-entitled workspace can create, edit, and delete permission groups for that workspace. On Sim Cloud, the workspace's billed account must be on the Enterprise plan; on self-hosted deployments you can enable it via ACCESS_CONTROL_ENABLED."
   },
   {
     question: "What happens to a workflow that was built before a block was restricted?",
     answer: "The workflow is not modified — it still exists and can be edited. However, any run that reaches a disallowed block will halt immediately with an error. The block must be removed or the user's group configuration must be updated before the workflow can run successfully."
   },
   {
     question: "Can a user be in multiple permission groups?",
-    answer: "No. Each user can belong to at most one permission group at a time. Adding a user to a new group automatically removes them from their current one."
+    answer: "A user can belong to at most one permission group per workspace, but can belong to different groups in different workspaces. Adding a user to a new group within the same workspace automatically removes them from their previous group in that workspace."
   },
   {
-    question: "What does a user see if they have no permission group assigned?",
-    answer: "Users with no group assignment have no restrictions. All blocks, model providers, and platform features are fully available to them."
+    question: "What does a user see if they have no permission group assigned in a workspace?",
+    answer: "Users with no group in a given workspace have no restrictions in that workspace. All blocks, model providers, and platform features are fully available to them there. Restrictions only apply in the specific workspaces where they are assigned to a group."
   },
   {
     question: "Does Mothership respect the same restrictions as the executor?",
-    answer: "Yes. Mothership reads the user's permission group before suggesting blocks or tools. Disallowed blocks are filtered out of the block picker, and disallowed tool types are skipped during workflow generation."
+    answer: "Yes. Mothership reads the user's permission group for the active workspace before suggesting blocks or tools. Disallowed blocks are filtered out of the block picker, and disallowed tool types are skipped during workflow generation."
   },
   {
     question: "Can I restrict access to specific workflows or workspaces?",
-    answer: "Access Control operates at the feature and block level, not at the individual workflow or workspace level. To restrict workspace access, use the organization membership and invitation settings."
+    answer: "Access Control operates at the feature and block level within a workspace. To restrict who can access the workspace itself, use workspace invitations and permissions. To apply different restrictions to different workflows, put them in different workspaces with distinct permission groups."
   },
   {
     question: "What is Auto-add new members?",
-    answer: "When a group has Auto-add new members enabled, any new member who joins the organization is automatically added to that group. Only one group per organization can have this setting enabled at a time."
+    answer: "When a group has Auto-add new members enabled, any new member who joins the workspace is automatically added to that group. Only one group per workspace can have this setting enabled at a time."
   }
 ]} />
 

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

@@ -12,7 +12,7 @@ Sim Enterprise provides advanced features for organizations with enhanced securi
 
 ## Access Control
 
-Define permission groups to control what features and integrations team members can use.
+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.
 
 ### Features
 
@@ -22,12 +22,12 @@ Define permission groups to control what features and integrations team members
 
 ### Setup
 
-1. Navigate to **Settings** → **Access Control** in your workspace
+1. Navigate to **Settings** → **Access Control** in the workspace you want to manage
 2. Create a permission group with your desired restrictions
-3. Add team members to the permission group
+3. Add workspace members to the permission group
 
 <Callout type="info">
-  Users not assigned to any permission group have full access. Permission restrictions are enforced at both UI and execution time.
+  Any workspace admin on an Enterprise-entitled workspace can manage permission groups. Users not assigned to any group have full access. Permission restrictions are enforced at both UI and execution time, and apply to workflows based on the workflow's workspace.
 </Callout>
 
 ---
@@ -93,7 +93,7 @@ curl -X DELETE "https://your-instance/api/v1/admin/workspaces/{workspaceId}/memb
 
 ### Notes
 
-- Enabling `ACCESS_CONTROL_ENABLED` automatically enables organizations, as access control requires organization membership.
+- Access Control is scoped per workspace. Set `ACCESS_CONTROL_ENABLED` and `NEXT_PUBLIC_ACCESS_CONTROL_ENABLED` to enable it on every workspace in a self-hosted deployment, bypassing the Enterprise plan check.
 - When `DISABLE_INVITATIONS` is set, users cannot send invitations. Use the Admin API to manage workspace and organization memberships instead.
 
 <FAQ items={[
@@ -104,5 +104,5 @@ curl -X DELETE "https://your-instance/api/v1/admin/workspaces/{workspaceId}/memb
   { question: "Which SSO providers are supported?", answer: "Sim supports SAML 2.0 and OIDC protocols, which means it works with virtually any enterprise identity provider including Okta, Azure AD (Entra ID), Google Workspace, and OneLogin. Configuration is done through Settings in the workspace UI." },
   { question: "How do I manage users when invitations are disabled?", answer: "Use the Admin API with your admin API key. You can create organizations, add members to organizations with specific roles, add users to workspaces with defined permissions, and remove users. All management is done through REST API calls authenticated with the x-admin-key header." },
   { question: "Can I scale Sim horizontally for high availability?", answer: "The Docker Compose setup is designed for single-node deployments. For production scaling, you can deploy on Kubernetes with multiple application replicas behind a load balancer. The database can be scaled independently using managed PostgreSQL services. Redis can be configured for session and cache management across multiple instances." },
-  { question: "How do access control permission groups work?", answer: "Permission groups let you restrict which AI providers, workflow blocks, and platform features are available to specific team members. Users not assigned to any group have full access. Restrictions are enforced at both the UI level (hiding restricted options) and at execution time (blocking unauthorized operations). Enabling access control automatically enables organization management." },
+  { question: "How do access control permission groups work?", answer: "Permission groups are created per workspace and let you restrict which AI providers, workflow blocks, and platform features are available to specific members of that workspace. Each user can belong to at most one group per workspace (and different groups in different workspaces). Users not assigned to any group have full access. Restrictions are enforced at both the UI level (hiding restricted options) and at execution time (blocking unauthorized operations) — execution enforcement is based on the workflow's workspace. Any workspace admin on an Enterprise-entitled workspace can manage permission groups." },
 ]} />

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

@@ -220,6 +220,6 @@ import { FAQ } from '@/components/ui/faq'
   { question: "Who can configure MCP servers in a workspace?", answer: "Users with Write permission can configure (add and update) MCP servers in workspace settings. Only Admin permission is required to delete MCP servers. Users with Read permission can view available MCP tools and execute them in agents and MCP Tool blocks. This means all workspace members with at least Read access can use MCP tools in their workflows." },
   { question: "Can I use MCP servers from multiple workspaces?", answer: "MCP servers are configured per workspace. Each workspace maintains its own set of MCP server connections. If you need the same MCP server in multiple workspaces, you need to configure it separately in each workspace's settings." },
   { question: "How do I update MCP tool schemas after a server changes its available tools?", answer: "Click the Refresh button on the MCP server in your workspace settings. This fetches the latest tool schemas from the server and automatically updates any agent blocks that use those tools with the new parameter definitions." },
-  { question: "Can permission groups restrict access to MCP tools?", answer: "Yes. Organization admins can create permission groups that disable MCP tools for specific members using the disableMcpTools configuration option. When this is enabled, affected users will not be able to add or use MCP tools in their workflows." },
+  { question: "Can permission groups restrict access to MCP tools?", answer: "Yes. On Enterprise-entitled workspaces, any workspace admin can create a permission group that disables MCP tools for its members using the disableMcpTools option. When this is enabled, affected users will not be able to add or use MCP tools in workflows that belong to that workspace." },
   { question: "What happens if an MCP server goes offline during workflow execution?", answer: "If the MCP server is unreachable during execution, the tool call will fail and return an error. In an Agent block, the AI may attempt to handle the failure gracefully. In a standalone MCP Tool block, the workflow step will fail. Check MCP server logs and verify the server is running and accessible to troubleshoot connectivity issues." },
 ]} />

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

@@ -202,9 +202,9 @@ import { FAQ } from '@/components/ui/faq'
   { 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: "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. Organization admins 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." },
+  { 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 advanced access control feature that lets organization admins define granular restrictions beyond the standard Read/Write/Admin roles. 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 members can access. Members can be assigned to groups, and new members can be auto-added." },
+  { 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." },
 ]} />