---
title: "Roles and Permissions"
---

import { Callout } from 'fumadocs-ui/components/callout'
import { Video } from '@/components/ui/video'

When you invite team members to your organization or workspace, you'll need to choose what level of access to give them. This guide explains what each permission level allows users to do, helping you understand team roles and what access each permission level provides.

## Workspaces and Organizations

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. 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

| Plan | Personal Workspaces | Shared Workspaces |
|------|---------------------|-------------------|
| **Free** | 1 | — |
| **Pro** | Up to 3 | — |
| **Max** | Up to 10 | — |
| **Team / Enterprise** | Unlimited | Unlimited (seat-gated invites) |

<Callout type="info">
  When a Team or Enterprise subscription is cancelled or downgraded, existing shared workspaces stay accessible to current members. New invitations are blocked until the organization is upgraded again.
</Callout>

## How to Invite Someone to a Workspace

<div className="mx-auto w-full overflow-hidden rounded-lg">
  <Video src="invitations.mp4" width={700} height={450} />
</div>

## Workspace Permission Levels

When inviting someone to a workspace, you can assign one of three permission levels:

| Permission | What They Can Do |
|------------|------------------|
| **Read** | View workflows, see execution results, but cannot make any changes |
| **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:

### Read Permission
**Perfect for:** Stakeholders, observers, or team members who need visibility but shouldn't make changes

**What they can do:**
- View all workflows in the workspace
- See workflow execution results and logs
- Browse workflow configurations and settings
- View environment variables (but not edit them)

**What they cannot do:**
- Create, edit, or delete workflows
- Run or deploy workflows
- Change any workspace settings
- Invite other users

### Write Permission  
**Perfect for:** Developers, content creators, or team members actively working on automation

**What they can do:**
- Everything Read users can do, plus:
- Create, edit, and delete workflows
- Run and deploy workflows
- Add, edit, and delete workspace environment variables
- Use all available tools and integrations
- Collaborate in real-time on workflow editing

**What they cannot do:**
- Invite or remove users from the workspace
- Change workspace settings
- Delete the workspace

### Admin Permission
**Perfect for:** Team leads, project managers, or technical leads who need to manage the workspace

**What they can do:**
- Everything Write users can do, plus:
- Invite new users to the workspace with any permission level
- Remove users from the workspace
- Manage workspace settings and integrations
- Configure external tool connections
- Delete workflows created by other users

**What they cannot do:**
- Delete the workspace (only the workspace owner can do this)
- Remove the workspace owner from the workspace

---

## Workspace Owner vs Admin

Every workspace has one **Owner** (the person who created it) plus any number of **Admins**.

### Workspace Owner
- Has all Admin permissions
- Can delete the workspace
- Cannot be removed from the workspace
- Can transfer ownership to another user

### Workspace Admin  
- Can do everything except delete the workspace or remove the owner
- 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.
</Callout>

---

## Common Scenarios

### Adding a New Developer to Your Team
1. **Organization level**: Invite them as an **Organization Member**
2. **Workspace level**: Give them **Write** permission so they can create and edit workflows

### Adding a Project Manager
1. **Organization level**: Invite them as an **Organization Member** 
2. **Workspace level**: Give them **Admin** permission so they can manage the team and see everything

### Adding a Stakeholder or Client
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

---

## Environment Variables

Users can create two types of environment variables:

### Personal Environment Variables
- Only visible to the individual user
- Available in all workflows they run
- 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

---

## Best Practices

### Start with Minimal Permissions
Give users the lowest permission level they need to do their job. You can always increase permissions later.

### Use Organization Structure Wisely
- Make trusted team leads **Organization Admins**
- Most team members should be **Organization Members**
- Reserve workspace **Admin** permissions for people who need to manage users

### Review Permissions Regularly
Periodically review who has access to what, especially when team members change roles or leave the company.

### Environment Variable Security
- Use personal environment variables for sensitive API keys
- Use workspace environment variables for shared configuration
- Regularly audit who has access to sensitive variables

---

## Organization Roles

An organization has three roles: **Owner**, **Admin**, and **Member**.

### Organization Owner
**What they can do:**
- Everything an Admin can do
- Transfer organization ownership to another user
- Only one Owner exists per organization

### Organization Admin
**What they can do:**
- 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
- Promote members to Admin or demote Admins to Member

<Callout type="info">
  Owners and Admins have the same day-to-day permissions. The only action reserved for the Owner is transferring ownership.
</Callout>

### Organization Member
**What they can do:**
- Access shared workspaces they've been specifically invited to
- View the list of organization members
- Cannot invite new people, create shared workspaces, or manage organization settings

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. 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 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." },
]} />