improvement(governance): org-ws-credential roles clarity

Author: icecrasher321

apps/docs/content/docs/en/platform/permissions.mdx

@@ -120,7 +120,7 @@ Every workspace has one **Owner** (the person who created it) plus any number of
 - Can be removed from the workspace by the owner or other admins
 
 <Callout type="info">
-  For shared (organization) workspaces, the organization's Owner and Admins are treated as Admins of every workspace in the organization, even without an explicit per-workspace invite.
+  For shared (organization) workspaces, the organization's Owner and Admins are full Admins of every workspace in the organization, even without an explicit per-workspace invite. They automatically see every organization workspace, have complete read, write, and management access, and their workspace role is fixed — it shows greyed out in the member list with a tooltip and cannot be changed.
 </Callout>
 
 ---
@@ -151,10 +151,30 @@ Users can create two types of environment variables:
 - Managed in **Settings**, then go to **Secrets**
 
 ### Workspace Environment Variables
-- **Read permission**: Can see variable names and values
-- **Write/Admin permission**: Can add, edit, and delete variables
-- Available to all workspace members
-- If a personal variable has the same name as a workspace variable, the personal one takes priority
+- **Read**: see variable names (the values stay hidden unless you're an admin of that secret)
+- **Write**: add new variables, and edit or delete ones you created
+- **Admin**: add, edit, delete, and view the values of any workspace variable
+- Workspace variables are a kind of workspace credential, so they follow the [Credential Access](#credential-access) rules below — workspace Admins are admins of all of them
+- Available to all workspace members; if a personal variable has the same name, the personal one takes priority
+
+---
+
+## Credential Access
+
+Workspace credentials — OAuth connections, service accounts, and workspace environment variables — have two roles of their own:
+
+- **Credential Member**: can use the credential in workflows.
+- **Credential Admin**: can use it and also edit, delete, and share it.
+
+These roles follow your workspace role:
+
+- **Workspace Admins are automatically Credential Admins** of every shared credential in the workspace (OAuth connections, service accounts, and workspace environment variables). Because organization Owners and Admins are workspace Admins everywhere, they are Credential Admins too. These automatic roles are fixed — they show greyed out with a tooltip in the credential's member list and cannot be changed.
+- **Read and Write members are Credential Members** by default — they can use shared credentials but cannot edit, delete, or share them unless someone makes them a Credential Admin (you are always an admin of credentials you create).
+- **Personal environment variables** are the exception: they stay private to their owner and are never shared with workspace admins.
+
+<Callout type="info">
+  A Credential Admin can both use and manage a credential, so a workspace Admin can run workflows that use any shared OAuth connection in the workspace — including one another member added.
+</Callout>
 
 ---
 
@@ -173,7 +193,7 @@ An organization has three roles: **Owner**, **Admin**, and **Member**.
 - Invite and remove team members from the organization
 - Create new shared workspaces under the organization
 - Manage billing, seat count, and subscription settings
-- Access all shared workspaces within the organization as a workspace Admin
+- Access every shared workspace in the organization as a workspace Admin automatically (no per-workspace invite), including administering the credentials inside them
 - Promote members to Admin or demote Admins to Member
 
 <Callout type="info">
@@ -194,6 +214,7 @@ import { FAQ } from '@/components/ui/faq'
   { question: "Can I restrict which integrations or model providers a team member can use?", answer: "Yes, on Enterprise-entitled organizations. Any organization owner or 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 to the organization and can govern either all workspaces or a specific subset — a user can belong to multiple groups but is governed by exactly one group in any given workspace." },
   { 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 organization owners and admins define granular restrictions beyond the standard Read/Write/Admin roles. Groups are scoped to the organization and can govern either all workspaces or a specific subset. A user can belong to multiple groups, but at most one governs them in any given workspace: a workspace-specific group takes precedence over an all-workspaces group, which takes precedence over the organization's default group. 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 are assigned manually, and an organization can designate one group as the default (always all-workspaces) that governs everyone not explicitly assigned — including external workspace members. Execution-time enforcement is based on the organization that owns the workflow's workspace, not the user's current UI context." },
+  { question: "Who can manage a workspace's credentials and secrets?", answer: "Workspace Admins are automatically Credential Admins of the workspace's shared credentials — OAuth connections, service accounts, and workspace environment variables — so they can use, edit, delete, and share them, and run workflows that rely on them. Organization Owners and Admins get this too because they are workspace Admins everywhere. Read and Write members get use-only access to shared credentials unless they are explicitly made a Credential Admin. Personal environment variables are never shared; they stay private to their owner." },
+  { question: "What are permission groups and how do they work?", answer: "Permission groups are an Enterprise access control feature that lets organization owners and admins define granular restrictions beyond the standard Read/Write/Admin roles. Groups are scoped to the organization and can govern either all workspaces or a specific subset. A user can belong to multiple groups, but at most one governs them in any given workspace: a workspace-specific group takes precedence over an all-workspaces group, which takes precedence over the organization's default group. 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 are assigned manually, and an organization can designate one group as the default (always all-workspaces) that governs everyone not explicitly assigned — including external workspace members. Restrictions are enforced based on the organization that owns the workflow's workspace, not on which workspace you're currently viewing." },
   { 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/sim/app/api/credentials/[id]/members/route.ts

@@ -5,20 +5,26 @@ import { createLogger } from '@sim/logger'
 import { generateId } from '@sim/utils/id'
 import { and, eq } from 'drizzle-orm'
 import { type NextRequest, NextResponse } from 'next/server'
-import { upsertWorkspaceCredentialMemberContract } from '@/lib/api/contracts/credentials'
+import {
+  upsertWorkspaceCredentialMemberContract,
+  type WorkspaceCredentialMember,
+} from '@/lib/api/contracts/credentials'
 import { parseRequest } from '@/lib/api/server'
 import { getSession } from '@/lib/auth'
 import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
 import { captureServerEvent } from '@/lib/posthog/server'
-import { getUserEntityPermissions } from '@/lib/workspaces/permissions/utils'
+import {
+  getUserEntityPermissions,
+  getUsersWithPermissions,
+} from '@/lib/workspaces/permissions/utils'
 
 const logger = createLogger('CredentialMembersAPI')
 
 interface RouteContext {
   params: Promise<{ id: string }>
 }
 
-async function requireWorkspaceAdminMembership(credentialId: string, userId: string) {
+async function requireCredentialAdmin(credentialId: string, userId: string) {
   const [cred] = await db
     .select({ id: credential.id, workspaceId: credential.workspaceId, type: credential.type })
     .from(credential)
@@ -30,6 +36,8 @@ async function requireWorkspaceAdminMembership(credentialId: string, userId: str
   const perm = await getUserEntityPermissions(userId, 'workspace', cred.workspaceId)
   if (perm === null) return null
 
+  const isWorkspaceAdmin = cred.type !== 'env_personal' && perm === 'admin'
+
   const [membership] = await db
     .select({ role: credentialMember.role, status: credentialMember.status })
     .from(credentialMember)
@@ -38,10 +46,12 @@ async function requireWorkspaceAdminMembership(credentialId: string, userId: str
     )
     .limit(1)
 
-  if (!membership || membership.status !== 'active' || membership.role !== 'admin') {
+  const isCredentialAdmin = membership?.status === 'active' && membership?.role === 'admin'
+
+  if (!isWorkspaceAdmin && !isCredentialAdmin) {
     return null
   }
-  return { ...membership, credentialType: cred.type, workspaceId: cred.workspaceId }
+  return { credentialType: cred.type, workspaceId: cred.workspaceId }
 }
 
 export const GET = withRouteHandler(async (_request: NextRequest, context: RouteContext) => {
@@ -54,7 +64,7 @@ export const GET = withRouteHandler(async (_request: NextRequest, context: Route
     const { id: credentialId } = await context.params
 
     const [cred] = await db
-      .select({ id: credential.id, workspaceId: credential.workspaceId })
+      .select({ id: credential.id, workspaceId: credential.workspaceId, type: credential.type })
       .from(credential)
       .where(eq(credential.id, credentialId))
       .limit(1)
@@ -72,7 +82,7 @@ export const GET = withRouteHandler(async (_request: NextRequest, context: Route
       return NextResponse.json({ error: 'Not found' }, { status: 404 })
     }
 
-    const members = await db
+    const explicitMembers = await db
       .select({
         id: credentialMember.id,
         userId: credentialMember.userId,
@@ -86,6 +96,48 @@ export const GET = withRouteHandler(async (_request: NextRequest, context: Route
       .innerJoin(user, eq(credentialMember.userId, user.id))
       .where(eq(credentialMember.credentialId, credentialId))
 
+    const byUser = new Map<string, WorkspaceCredentialMember>(
+      explicitMembers.map((m) => [
+        m.userId,
+        {
+          id: m.id,
+          userId: m.userId,
+          role: m.role,
+          status: m.status,
+          joinedAt: m.joinedAt ? m.joinedAt.toISOString() : null,
+          userName: m.userName,
+          userEmail: m.userEmail,
+          roleSource: 'explicit' as const,
+        },
+      ])
+    )
+
+    if (cred.type !== 'env_personal') {
+      const workspaceMembers = await getUsersWithPermissions(cred.workspaceId)
+      for (const wsMember of workspaceMembers) {
+        if (wsMember.permissionType !== 'admin') continue
+        const existing = byUser.get(wsMember.userId)
+        if (existing) {
+          existing.role = 'admin'
+          existing.status = 'active'
+          existing.roleSource = 'workspace-admin'
+        } else {
+          byUser.set(wsMember.userId, {
+            id: `workspace-admin-${wsMember.userId}`,
+            userId: wsMember.userId,
+            role: 'admin',
+            status: 'active',
+            joinedAt: null,
+            userName: wsMember.name,
+            userEmail: wsMember.email,
+            roleSource: 'workspace-admin',
+          })
+        }
+      }
+    }
+
+    const members = Array.from(byUser.values())
+
     return NextResponse.json({ members })
   } catch (error) {
     logger.error('Failed to fetch credential members', { error })
@@ -102,7 +154,7 @@ export const POST = withRouteHandler(async (request: NextRequest, context: Route
 
     const { id: credentialId } = await context.params
 
-    const admin = await requireWorkspaceAdminMembership(credentialId, session.user.id)
+    const admin = await requireCredentialAdmin(credentialId, session.user.id)
     if (!admin) {
       logger.warn('Credential member share denied', {
         credentialId,
@@ -124,6 +176,19 @@ export const POST = withRouteHandler(async (request: NextRequest, context: Route
     if (!parsed.success) return parsed.response
 
     const { userId, role } = parsed.data.body
+
+    const targetWorkspacePerm = await getUserEntityPermissions(
+      userId,
+      'workspace',
+      admin.workspaceId
+    )
+    if (targetWorkspacePerm === 'admin' && role !== 'admin') {
+      return NextResponse.json(
+        { error: 'Workspace admins are automatically credential admins and cannot be demoted' },
+        { status: 400 }
+      )
+    }
+
     const now = new Date()
 
     const [existing] = await db
@@ -233,7 +298,7 @@ export const DELETE = withRouteHandler(async (request: NextRequest, context: Rou
       return NextResponse.json({ error: 'userId query parameter required' }, { status: 400 })
     }
 
-    const admin = await requireWorkspaceAdminMembership(credentialId, session.user.id)
+    const admin = await requireCredentialAdmin(credentialId, session.user.id)
     if (!admin) {
       logger.warn('Credential member removal denied', {
         credentialId,
@@ -262,6 +327,20 @@ export const DELETE = withRouteHandler(async (request: NextRequest, context: Rou
       return NextResponse.json({ error: 'Member not found' }, { status: 404 })
     }
 
+    if (admin.credentialType !== 'env_personal') {
+      const targetWorkspacePerm = await getUserEntityPermissions(
+        targetUserId,
+        'workspace',
+        admin.workspaceId
+      )
+      if (targetWorkspacePerm === 'admin') {
+        return NextResponse.json(
+          { error: 'Workspace admins are automatically credential admins and cannot be removed' },
+          { status: 400 }
+        )
+      }
+    }
+
     const revoked = await db.transaction(async (tx) => {
       if (target.role === 'admin') {
         const activeAdmins = await tx

apps/sim/app/api/credentials/route.ts

@@ -498,11 +498,8 @@ export const POST = withRouteHandler(async (request: NextRequest) => {
 
     const now = new Date()
     const credentialId = generateId()
-    const {
-      ownerId: workspaceOwnerId,
-      memberUserIds: workspaceMemberUserIds,
-      adminUserIds: workspaceAdminUserIds,
-    } = await getWorkspaceMembership(workspaceId)
+    const { ownerId: workspaceOwnerId, memberUserIds: workspaceMemberUserIds } =
+      await getWorkspaceMembership(workspaceId)
 
     await db.transaction(async (tx) => {
       // service_account has no DB-level unique index on (workspaceId, providerId,
@@ -537,8 +534,7 @@ export const POST = withRouteHandler(async (request: NextRequest) => {
       if ((type === 'env_workspace' || type === 'service_account') && workspaceOwnerId) {
         if (workspaceMemberUserIds.length > 0) {
           for (const memberUserId of workspaceMemberUserIds) {
-            const isAdmin =
-              memberUserId === session.user.id || workspaceAdminUserIds.has(memberUserId)
+            const isAdmin = memberUserId === session.user.id
             await tx.insert(credentialMember).values({
               id: generateId(),
               credentialId,

apps/sim/app/api/organizations/[id]/roster/route.ts

@@ -117,16 +117,25 @@ export const GET = withRouteHandler(
         permissionsByUser.set(row.userId, list)
       }
 
-      const members = memberRows.map((row) => ({
-        memberId: row.memberId,
-        userId: row.userId,
-        role: row.role,
-        createdAt: row.createdAt,
-        name: row.userName,
-        email: row.userEmail,
-        image: row.userImage,
-        workspaces: permissionsByUser.get(row.userId) ?? [],
-      }))
+      const members = memberRows.map((row) => {
+        const isOrgAdmin = row.role === 'owner' || row.role === 'admin'
+        return {
+          memberId: row.memberId,
+          userId: row.userId,
+          role: row.role,
+          createdAt: row.createdAt,
+          name: row.userName,
+          email: row.userEmail,
+          image: row.userImage,
+          workspaces: isOrgAdmin
+            ? orgWorkspaces.map((ws) => ({
+                workspaceId: ws.id,
+                workspaceName: ws.name,
+                permission: 'admin' as const,
+              }))
+            : (permissionsByUser.get(row.userId) ?? []),
+        }
+      })
 
       const externalPermissionRows =
         orgWorkspaceIds.length > 0