Feedback 2

Author: katmayb

src/langsmith/administration-overview.mdx

@@ -4,6 +4,7 @@ sidebarTitle: Overview
 ---
 
 import OrgWorkspaceRole from '/snippets/langsmith/multi-workspace-org-roles.mdx';
+import PermissionReference from '/snippets/langsmith/permissions-reference.mdx';
 
 This overview covers topics related to managing users, organizations, and workspaces within LangSmith.
 
@@ -119,21 +120,25 @@ To see how to create a service key or Personal Access Token, see the [setup guid
 
 ### Organization roles
 
-Organization roles are distinct from the Enterprise feature (RBAC) below and are used in the context of multiple [workspaces](#workspaces). Your organization role determines your workspace membership characteristics and your organization-level permissions. See the [organization setup guide](/langsmith/set-up-a-workspace#organization-roles) for more information.
+Organization roles are distinct from the [Enterprise feature workspace RBAC](#workspace-roles-rbac) and are used in the context of multiple [workspaces](#workspaces). Your organization role determines your workspace membership characteristics and your [organization-level permissions](/langsmith/organization-workspace-operations).
 
 The organization role selected also impacts workspace membership as described here:
 
-* `Organization Admin` grants full access to manage all organization configuration, users, billing, and workspaces. **An `Organization Admin` has `Admin` access to all workspaces in an organization**
-* `Organization User` may read organization information but cannot execute any write actions at the organization level. An `Organization User` may create Personal Access Tokens. **An `Organization User` can be added to a subset of workspaces and assigned workspace roles as usual (if RBAC is enabled), which specify permissions at the workspace level.**
-* `Organization Viewer` is equivalent to `Organization User`, but **cannot** create Personal Access Tokens. (for self-hosted, available in Helm chart version 0.11.25+)
+- [Organization Admin](/langsmith/rbac#organization-admin) grants full access to manage all organization configuration, users, billing, and workspaces.
+    - An Organization Admin has `Admin` access to all workspaces in an organization.
+- [Organization User](/langsmith/rbac#organization-user) may read organization information but cannot execute any write actions at the organization level. An Organization User may create [Personal Access Tokens](#personal-access-tokens-pats).
+    - An Organization User can be added to a subset of workspaces and assigned workspace roles as usual (if RBAC is enabled), which specify permissions at the workspace level.
+- [Organization Viewer](/langsmith/rbac#organization-viewer) is equivalent to Organization User, but **cannot** create Personal Access Tokens. (for self-hosted, available in Helm chart version 0.11.25+).
 
 <Info>
 <OrgWorkspaceRole/>
 
 See [security settings](/langsmith/manage-organization-by-api#security-settings) for instructions on how to disable PAT creation for the entire organization.
 </Info>
 
-See the table below for all organization permissions:
+For more information on setting up organizations and workspaces, refer to the [organization setup guide](/langsmith/set-up-a-workspace#organization-roles) for more information.
+
+The following table provdies an overview of organization level permissions:
 
 |                                             | Organization Viewer | Organization User | Organization Admin |
 | ------------------------------------------- | ------------------- | ----------------- | ------------------ |
@@ -153,6 +158,7 @@ See the table below for all organization permissions:
 | Update data retention settings              | ❌                   | ❌                 | ✅                  |
 | Update usage limits                         | ❌                   | ❌                 | ✅                  |
 
+<PermissionReference/>
 
 ### Workspace roles (RBAC)
 
@@ -162,17 +168,19 @@ RBAC (Role-Based Access Control) is a feature that is only available to Enterpri
 
 Roles are used to define the set of permissions that a user has within a workspace. There are three built-in system roles that cannot be edited:
 
-* `Admin` - has full access to all resources within the workspace
-* `Viewer` - has read-only access to all resources within the workspace
-* `Editor` - has full permissions except for workspace management (adding/removing users, changing roles, configuring service keys)
+- [Workspace Admin](/langsmith/rbac#workspace-admin) has full access to all resources within the workspace.
+- [Workspace Editor](/langsmith/rbac#workspace-editor) has full permissions except for workspace management (adding/removing users, changing roles, configuring service keys).
+- [Workspace Viewer](/langsmith/rbac#workspace-viewer) has read-only access to all resources within the workspace.
 
-Organization admins can also create/edit custom roles with specific permissions for different resources.
+[Organization admins](/langsmith/rbac#organization-admin) can also create/edit custom roles with specific permissions for different resources.
 
-Roles can be managed in organization settings under the `Roles` tab:
+Roles can be managed in **Organization Settings** under the **Roles** tab:
 
-![Roles](/langsmith/images/roles-tab-rbac.png)
+![](/langsmith/images/roles-tab-rbac.png)
 
-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/organization-workspace-operations) page. For more details on assigning and creating roles, refer to the [User Management](/langsmith/user-management) guide.
+- For comprehensive documentation on roles and permissions, refer to the [Role-based access control](/langsmith/rbac) guide.
+- For more details on assigning and creating roles, refer to the [User Management](/langsmith/user-management) guide.
+- <PermissionReference/>
 
 ## Best Practices
 

src/langsmith/organization-workspace-operations.mdx

@@ -556,12 +556,12 @@ These operations are available to all authenticated users and don't require spec
 
 ### Organization to workspace
 
-- **Organization Admin** automatically has full permissions in all workspaces.
-- **Organization User** and **Organization Viewer** only get workspace access when explicitly added to workspaces with workspace-level roles.
+- [Organization Admin](/langsmith/rbac#organization-admin) automatically has full permissions in all workspaces.
+- [Organization User](/langsmith/rbac#organization-user) and [Organization Viewer](/langsmith/rbac#organization-viewer) only get workspace access when explicitly added to workspaces with workspace-level roles.
 
 For detailed role definitions, refer to [Organization roles](/langsmith/rbac#organization-roles) and [Workspace roles](/langsmith/rbac#workspace-roles).
 
 ### Workspace role independence
 
 - Users can have different workspace roles in different workspaces.
-- A user might be a Workspace Admin in one workspace and a Workspace Viewer in another.
+- A user might be a [Workspace Admin](/langsmith/rbac#workspace-admin) in one workspace and a [Workspace Viewer](/langsmith/rbac#workspace-viewer) in another.

src/langsmith/rbac.mdx

@@ -4,6 +4,7 @@ sidebarTitle: Role-based access control
 ---
 
 import OrgWorkspaceRole from '/snippets/langsmith/multi-workspace-org-roles.mdx';
+import PermissionReference from '/snippets/langsmith/permissions-reference.mdx';
 
 This reference explains LangSmith's Role-Based Access Control (RBAC) system for managing organization-level and workspace-level permissions.
 
@@ -51,16 +52,18 @@ In organizations limited to a single workspace, all users are [Organization Admi
 - `organization:read` - Read access to all organization information
 - `organization:pats:create` - Create organization-level [personal access tokens](/langsmith/administration-overview#personal-access-tokens-pats)
 
+<PermissionReference/>
+
 **Key Capabilities**:
-- Manage organization settings and branding
+- Manage [organization settings](/langsmith/set-up-a-workspace#set-up-an-organization) 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
+- Manage [billing](/langsmith/billing) and subscription plans
+- Create and delete [workspaces](/langsmith/set-up-a-workspace)
 - Invite and remove organization members
 - Assign organization and workspace roles to members
-- Create and manage custom roles
+- Create and manage [custom roles](#custom-roles)
 - Configure RBAC and ABAC (Attribute-Based Access Control) policies (Note that ABAC is in private preview)
-- View organization usage and analytics
+- View organization [usage](/langsmith/administration-overview#usage-limits) and analytics
 
 For details on setting up and managing your organization, refer to the [Administration Overview](/langsmith/administration-overview#organizations).
 
@@ -72,10 +75,12 @@ For details on setting up and managing your organization, refer to the [Administ
 - `organization:read` - Read access to organization information
 - `organization:pats:create` - Create personal access tokens
 
+<PermissionReference/>
+
 **Key Capabilities**:
 - View organization members and workspaces
 - View organization settings (but not modify)
-- Create personal access tokens for API access
+- Create [personal access tokens](/langsmith/administration-overview#personal-access-tokens-pats) for API access
 - Join workspaces they're invited to
 
 **Restrictions**:
@@ -94,6 +99,8 @@ You can add an Organization User to a subset of workspaces and assigned workspac
 **Permissions**:
 - `organization:read` - Read access to organization information
 
+<PermissionReference/>
+
 **Key Capabilities**:
 - View organization members and workspaces
 - View organization settings
@@ -109,12 +116,12 @@ Workspace roles are part of the **Enterprise RBAC feature** and control what use
 
 | 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 |
+| [Workspace Admin](#workspace-admin) | Full permissions for all resources and ability to manage workspace |
+| [Workspace Editor](#workspace-editor) | Full permissions for most resources, cannot manage workspace settings or delete certain resources |
+| [Workspace Viewer](#workspace-viewer) | Read-only access to all workspace resources |
 
 <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.
+RBAC (Role-Based Access Control) is a feature that is only available to [Enterprise](https://langchain.com/pricing) 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
@@ -125,12 +132,14 @@ RBAC (Role-Based Access Control) is a feature that is only available to Enterpri
 - All create, read, update, delete, and share permissions for all resource types
 - Workspace management capabilities
 
+<PermissionReference/>
+
 #### Workspace Editor
 
-**Description**: Default role with full permissions for most resources. Cannot manage workspace settings or delete certain critical resources.
+**Description**: Role with full permissions for most resources. Cannot manage workspace settings or delete certain critical resources.
 
 **Key Differences from Admin**:
-- Cannot delete runs
+- Cannot delete [runs](/langsmith/observability#runs)
 - Cannot manage workspace settings (add/remove members, change workspace name, etc.)
 
 #### Workspace Viewer
@@ -139,6 +148,8 @@ RBAC (Role-Based Access Control) is a feature that is only available to Enterpri
 
 **Permissions**: Read-only access to all resource types.
 
+<PermissionReference/>
+
 <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>
@@ -147,11 +158,11 @@ For step-by-step instructions on assigning workspace roles to users, refer to th
 
 <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.
+[Organization Admins](#organization-admin) 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.
+Custom roles are created at the [organization](/langsmith/administration-overview#organizations) level and can be assigned to users in any [workspace](/langsmith/administration-overview#workspaces) within that organization.
 
 **Steps**:
 1. Navigate to Organization **Settings** > **Roles**.

src/snippets/langsmith/permissions-reference.mdx

@@ -0,0 +1 @@
+For a comprehensive list of required permissions along with the operations and roles that can perform them, refer to the [Organization and workspace reference](/langsmith/organization-and-workspace-operations).