WIP rbac and workspace ops docs ref

src/docs.json

@@ -877,8 +877,15 @@
                       "langsmith/data-purging-compliance"
                     ]
                   },
+                  {
+                    "group": "Access control & Authentication",
+                    "pages": [
+                      "langsmith/rbac",
+                      "langsmith/workspace-operations",
+                      "langsmith/authentication-methods"
+                    ]
+                  },
                   "langsmith/scalability-and-resilience",
-                  "langsmith/authentication-methods",
                   "langsmith/faq",
                   "langsmith/regions-faq",
                   "langsmith/pricing-faq"

src/langsmith/administration-overview.mdx

@@ -170,7 +170,7 @@ Roles can be managed in organization settings under the `Roles` tab:
 
 ![Roles](/langsmith/images/roles-tab-rbac.png)
 
-For more details on assigning and creating roles, see the [access control setup guide](/langsmith/user-management).
+For comprehensive documentation on roles and permissions, refer to the [Role-based access control](/langsmith/rbac) guide. For a detailed operations reference table, refer to the [Workspace Operations](/langsmith/workspace-operations) page. For more details on assigning and creating roles, refer to the [User Management](/langsmith/user-management) guide.
 
 ## Best Practices
 

src/langsmith/rbac.mdx

@@ -0,0 +1,175 @@
+---
+title: Role-based access control
+sidebarTitle: Role-based access control
+---
+
+This reference explains LangSmith's Role-Based Access Control (RBAC) system for managing workspace-level permissions.
+
+<Note>
+RBAC (Role-Based Access Control) is an Enterprise feature for managing workspace-level permissions. If you are interested in this feature, [contact our sales team](https://www.langchain.com/contact-sales). Other plans default to using the Admin role for all users.
+</Note>
+
+LangSmith's RBAC system manages user permissions within workspaces. RBAC allows you to control who can access your LangSmith [workspace](/langsmith/administration-overview#workspaces) and what they can do within it.
+
+Each user has:
+- One [**organization role**](#organization-roles) that applies across the entire organization (separate from RBAC, available on all plans).
+- One [**workspace role**](#workspace-roles) per workspace they're a member of (requires Enterprise RBAC feature).
+
+On Enterprise plans, organizations can create [custom workspace roles](#custom-roles) with granular permission combinations.
+
+To learn how to set up RBAC and assign roles to users, refer to the [User Management guide](/langsmith/user-management#set-up-access-control).
+
+<Note>
+For a comprehensive reference table of workspace-level and organization-level operations and which roles can perform them, refer to the [Workspace Operations Reference](/langsmith/workspace-operations).
+</Note>
+
+## Role types
+
+### Organization roles
+
+Organization roles are **distinct from the RBAC feature** and are used to manage organization-wide capabilities. These roles are available on all plans.
+
+| Role | Description |
+|------|-------------|
+| Organization Admin | Full permissions to manage organization configuration, users, billing, and workspaces |
+| Organization User | Read access to organization information and ability to create personal access tokens |
+| Organization Viewer | Read-only access to organization information |
+
+### Workspace roles
+
+Workspace roles are part of the **Enterprise RBAC feature** and control what users can do with resources inside a workspace:
+
+| Role | Description |
+|------|-------------|
+| Workspace Admin | Full permissions for all resources and ability to manage workspace |
+| Workspace Editor | Full permissions for most resources, cannot manage workspace settings or delete certain resources |
+| Workspace Viewer | Read-only access to all workspace resources |
+
+## Organization roles
+
+<Info>
+Organization roles are **distinct from the RBAC feature** and are available on all plans. They control organization-wide capabilities and workspace membership. For more details, see the [Administration Overview](/langsmith/administration-overview#organization-roles).
+</Info>
+
+### Organization Admin
+
+**Description**: Full permissions to manage all organization configuration, users, billing, and workspaces.
+
+**Permissions**:
+- `organization:manage` - Full control over organization settings, SSO, security, billing
+- `organization:read` - Read access to all organization information
+- `organization:pats:create` - Create organization-level personal access tokens
+
+**Key Capabilities**:
+- Manage organization settings and branding
+- Configure [SSO and authentication methods](/langsmith/user-management#set-up-saml-sso-for-your-organization)
+- Manage billing and subscription plans
+- Create and delete workspaces
+- Invite and remove organization members
+- Assign organization and workspace roles to members
+- Create and manage custom roles
+- Configure RBAC and ABAC (Attribute-Based Access Control) policies
+- Manage organization-level API keys and service accounts
+- View organization usage and analytics
+
+For details on setting up and managing your organization, refer to the [Administration Overview](/langsmith/administration-overview#organizations).
+
+### Organization User
+
+**Description**: Read access to organization information and ability to create personal access tokens.
+
+**Permissions**:
+- `organization:read` - Read access to organization information
+- `organization:pats:create` - Create personal access tokens
+
+**Key Capabilities**:
+- View organization members and workspaces
+- View organization settings (but not modify)
+- Create personal access tokens for API access
+- Join workspaces they're invited to
+
+**Restrictions**:
+- Cannot modify organization settings
+- Cannot manage billing or subscriptions
+- Cannot create or delete workspaces
+- Cannot invite or remove organization members
+- Cannot manage roles or permissions
+
+### Organization Viewer
+
+**Description**: Read-only access to organization information.
+
+**Permissions**:
+- `organization:read` - Read access to organization information
+
+**Key Capabilities**:
+- View organization members and workspaces
+- View organization settings
+
+**Restrictions**:
+- Cannot modify anything at the organization level
+- Cannot create personal access tokens
+- Cannot manage billing, workspaces, or members
+
+## Workspace roles
+
+<Note>
+RBAC (Role-Based Access Control) is a feature that is only available to Enterprise customers. If you are interested in this feature, [contact our sales team](https://www.langchain.com/contact-sales). Other plans default to using the Admin role for all users.
+</Note>
+
+### Workspace Admin
+
+**Description**: Default role with full permissions for all resources and ability to manage workspace.
+
+**Permissions**:
+- All create, read, update, delete, and share permissions for all resource types
+- Workspace management capabilities
+
+### Workspace Editor
+
+**Description**: Default role with full permissions for most resources. Cannot manage workspace settings or delete certain critical resources.
+
+**Key Differences from Admin**:
+- Cannot delete annotation queues
+- Cannot create or delete projects (can only read and update)
+- Cannot delete datasets
+- Cannot share datasets
+- Cannot delete deployments
+- Cannot delete runs
+- Cannot manage workspace settings (add/remove members, change workspace name, etc.)
+
+### Workspace Viewer
+
+**Description**: Read-only access to all workspace resources.
+
+**Permissions**: Read-only access to all resource types.
+
+<Tip>
+For step-by-step instructions on assigning workspace roles to users, refer to the [User Management guide](/langsmith/user-management#assign-a-role-to-a-user).
+</Tip>
+
+## Custom roles
+
+<Info>Creating custom roles is available for organizations on the Enterprise plan.</Info>
+
+Organization Admins can create custom roles with specific combinations of permissions tailored to their organization's needs.
+
+### Creating custom roles
+
+Custom roles are created at the organization level and can be assigned to users in any workspace within that organization.
+
+**Steps**:
+1. Navigate to Organization **Settings** > **Roles**.
+2. Click **Create Custom Role**.
+3. Select the permissions to include in the role.
+4. Assign the custom role to users in specific workspaces.
+
+For details on which specific permissions are required for each operation, refer to the [Workspace Operations Reference](/langsmith/workspace-operations).
+
+Note the following details on custom roles:
+
+- Custom roles can only be created and managed by Organization Admins.
+- Custom roles are organization-specific (not transferable between organizations).
+- Each custom role can have any combination of workspace-level permissions.
+- Custom roles cannot have organization-level permissions.
+- Users can have different roles (including custom roles) in different workspaces.

src/langsmith/user-management.mdx

@@ -21,6 +21,8 @@ You may find it helpful to read the [Administration overview](/langsmith/adminis
 
 LangSmith relies on RBAC to manage user permissions within a [workspace](/langsmith/administration-overview#workspaces). This allows you to control who can access your LangSmith workspace and what they can do within it. Only users with the `workspace:manage` permission can manage access control settings for a workspace.
 
+For a complete reference of workspace roles and their permissions, refer to the [Role-based access control](/langsmith/rbac#workspace-roles) guide. For specific operations each role can perform, refer to the [Workspace Operations Reference](/langsmith/workspace-operations).
+
 ### Create a role
 
 By default, LangSmith comes with a set of system roles: