Skip to content

Commit 2770c42

Browse files
katmaybkatmayb
committed
WIP rbac and workspace ops docs ref
1 parent e4e7ef3 commit 2770c42

File tree

3 files changed

+926
-1
lines changed

3 files changed

+926
-1
lines changed

‎src/docs.json‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -876,8 +876,15 @@
876876
"langsmith/data-purging-compliance"
877877
]
878878
},
879+
{
880+
"group": "Access control & Authentication",
881+
"pages": [
882+
"langsmith/workspace-operations",
883+
"langsmith/rbac",
884+
"langsmith/authentication-methods"
885+
]
886+
},
879887
"langsmith/scalability-and-resilience",
880-
"langsmith/authentication-methods",
881888
"langsmith/faq",
882889
"langsmith/regions-faq",
883890
"langsmith/pricing-faq"

‎src/langsmith/rbac.mdx‎

Lines changed: 351 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,351 @@
1+
---
2+
title: Role-based access control
3+
sidebarTitle: Role-based access control
4+
---
5+
6+
This guide explains LangSmith's Role-Based Access Control (RBAC), including role types, permissions, and best practices. For a comprehensive reference table of operations and which roles can perform them, see [Workspace Operations Reference](/langsmith/workspace-operations).
7+
8+
## Overview
9+
10+
LangSmith uses a two-tier RBAC system:
11+
12+
- **Workspace-level permissions**: Control access to resources within a specific workspace (projects, datasets, runs, etc.)
13+
- **Organization-level permissions**: Control access to organization-wide settings, billing, member management, and workspace creation
14+
15+
Each user can have:
16+
- One **organization role** that applies across the entire organization
17+
- One **workspace role** per workspace they're a member of
18+
19+
Additionally, organizations can create [custom roles](#custom-roles) with granular permission combinations.
20+
21+
## Role Types
22+
23+
Workspace roles control what users can do with resources inside a workspace:
24+
25+
| Role | Display Name | Description |
26+
|------|--------------|-------------|
27+
| `WORKSPACE_ADMIN` | Admin | Full permissions for all resources and ability to manage workspace |
28+
| `WORKSPACE_USER` | User | Full permissions for most resources, cannot manage workspace settings or delete certain resources |
29+
| `WORKSPACE_VIEWER` | Viewer | Read-only access to all workspace resources |
30+
31+
Organization roles control organization-wide capabilities:
32+
33+
| Role | Display Name | Description |
34+
|------|--------------|-------------|
35+
| `ORGANIZATION_ADMIN` | Organization Admin | Full permissions to manage organization configuration, users, billing, and workspaces |
36+
| `ORGANIZATION_USER` | Organization User | Read access to organization information and ability to create personal access tokens |
37+
| `ORGANIZATION_VIEWER` | Organization Viewer | Read-only access to organization information |
38+
39+
## Workspace Roles
40+
41+
### Workspace Admin (`WORKSPACE_ADMIN`)
42+
43+
**Description**: Default role with full permissions for all resources and ability to manage workspace.
44+
45+
**All Permissions**:
46+
- All create, read, update, delete, and share permissions for all resource types
47+
- Workspace management capabilities
48+
49+
<details>
50+
<summary>View Complete Permission List</summary>
51+
52+
- `annotation-queues:create`
53+
- `annotation-queues:delete`
54+
- `annotation-queues:read`
55+
- `annotation-queues:update`
56+
- `charts:create`
57+
- `charts:delete`
58+
- `charts:read`
59+
- `charts:update`
60+
- `datasets:create`
61+
- `datasets:delete`
62+
- `datasets:read`
63+
- `datasets:share`
64+
- `datasets:update`
65+
- `deployments:create`
66+
- `deployments:delete`
67+
- `deployments:read`
68+
- `deployments:update`
69+
- `feedback:create`
70+
- `feedback:delete`
71+
- `feedback:read`
72+
- `feedback:update`
73+
- `projects:create`
74+
- `projects:delete`
75+
- `projects:read`
76+
- `projects:update`
77+
- `prompts:create`
78+
- `prompts:delete`
79+
- `prompts:read`
80+
- `prompts:share`
81+
- `prompts:update`
82+
- `rules:create`
83+
- `rules:delete`
84+
- `rules:read`
85+
- `rules:update`
86+
- `runs:create`
87+
- `runs:delete`
88+
- `runs:read`
89+
- `runs:share`
90+
- `workspaces:manage`
91+
- `workspaces:read`
92+
93+
</details>
94+
95+
### Workspace User (`WORKSPACE_USER`)
96+
97+
**Description**: Default role with full permissions for most resources. Cannot manage workspace settings or delete certain critical resources.
98+
99+
**Key Differences from Admin**:
100+
- ❌ Cannot delete annotation queues
101+
- ❌ Cannot create or delete projects (can only read and update)
102+
- ❌ Cannot delete datasets
103+
- ❌ Cannot share datasets
104+
- ❌ Cannot delete deployments
105+
- ❌ Cannot delete runs
106+
- ❌ Cannot manage workspace settings (add/remove members, change workspace name, etc.)
107+
108+
<details>
109+
<summary>View Complete Permission List</summary>
110+
111+
- `annotation-queues:create`
112+
- `annotation-queues:read`
113+
- `annotation-queues:update`
114+
- `charts:create`
115+
- `charts:delete`
116+
- `charts:read`
117+
- `charts:update`
118+
- `datasets:create`
119+
- `datasets:read`
120+
- `datasets:update`
121+
- `deployments:create`
122+
- `deployments:read`
123+
- `deployments:update`
124+
- `feedback:create`
125+
- `feedback:delete`
126+
- `feedback:read`
127+
- `feedback:update`
128+
- `projects:read`
129+
- `projects:update`
130+
- `prompts:create`
131+
- `prompts:delete`
132+
- `prompts:read`
133+
- `prompts:share`
134+
- `prompts:update`
135+
- `rules:create`
136+
- `rules:delete`
137+
- `rules:read`
138+
- `rules:update`
139+
- `runs:create`
140+
- `runs:read`
141+
- `runs:share`
142+
- `workspaces:read`
143+
144+
</details>
145+
146+
### Workspace Viewer (`WORKSPACE_VIEWER`)
147+
148+
**Description**: Read-only access to all workspace resources.
149+
150+
**Permissions**: Read-only access to all resource types.
151+
152+
<details>
153+
<summary>View Complete Permission List</summary>
154+
155+
- `annotation-queues:read`
156+
- `charts:read`
157+
- `datasets:read`
158+
- `deployments:read`
159+
- `feedback:read`
160+
- `projects:read`
161+
- `prompts:read`
162+
- `rules:read`
163+
- `runs:read`
164+
- `workspaces:read`
165+
166+
</details>
167+
168+
## Organization Roles
169+
170+
### Organization Admin (`ORGANIZATION_ADMIN`)
171+
172+
**Description**: Full permissions to manage all organization configuration, users, billing, and workspaces.
173+
174+
**Permissions**:
175+
- `organization:manage` - Full control over organization settings, SSO, security, billing
176+
- `organization:read` - Read access to all organization information
177+
- `organization:pats:create` - Create organization-level personal access tokens
178+
179+
**Key Capabilities**:
180+
- Manage organization settings and branding
181+
- Configure SSO and authentication methods
182+
- Manage billing and subscription plans
183+
- Create and delete workspaces
184+
- Invite and remove organization members
185+
- Assign organization and workspace roles to members
186+
- Create and manage custom roles
187+
- Configure RBAC and ABAC (Attribute-Based Access Control) policies
188+
- Manage organization-level API keys and service accounts
189+
- View organization usage and analytics
190+
191+
### Organization User (`ORGANIZATION_USER`)
192+
193+
**Description**: Read access to organization information and ability to create personal access tokens.
194+
195+
**Permissions**:
196+
- `organization:read` - Read access to organization information
197+
- `organization:pats:create` - Create personal access tokens
198+
199+
**Key Capabilities**:
200+
- View organization members and workspaces
201+
- View organization settings (but not modify)
202+
- Create personal access tokens for API access
203+
- Join workspaces they're invited to
204+
205+
**Restrictions**:
206+
- ❌ Cannot modify organization settings
207+
- ❌ Cannot manage billing or subscriptions
208+
- ❌ Cannot create or delete workspaces
209+
- ❌ Cannot invite or remove organization members
210+
- ❌ Cannot manage roles or permissions
211+
212+
### Organization Viewer (`ORGANIZATION_VIEWER`)
213+
214+
**Description**: Read-only access to organization information.
215+
216+
**Permissions**:
217+
- `organization:read` - Read access to organization information
218+
219+
**Key Capabilities**:
220+
- View organization members and workspaces
221+
- View organization settings
222+
223+
**Restrictions**:
224+
- ❌ Cannot modify anything at the organization level
225+
- ❌ Cannot create personal access tokens
226+
- ❌ Cannot manage billing, workspaces, or members
227+
228+
## Common Operations by Role
229+
230+
This section shows common user workflows and required permissions. For a complete list of all operations, see the [Workspace Operations Reference](/langsmith/workspace-operations).
231+
232+
### Tracing and Monitoring
233+
234+
| Action | Required Permission | Workspace Admin | Workspace User | Workspace Viewer |
235+
|--------|---------------------|:---------------:|:--------------:|:----------------:|
236+
| Send traces from SDK | `runs:create` | ✅ | ✅ | ❌ |
237+
| View traces | `runs:read` | ✅ | ✅ | ✅ |
238+
| Create a project | `projects:create` | ✅ | ❌ | ❌ |
239+
| View project dashboard | `projects:read` | ✅ | ✅ | ✅ |
240+
| Share a trace publicly | `runs:share` | ✅ | ✅ | ❌ |
241+
| Delete traces | `runs:delete` | ✅ | ❌ | ❌ |
242+
| Add feedback to a run | `feedback:create` | ✅ | ✅ | ❌ |
243+
| View feedback | `feedback:read` | ✅ | ✅ | ✅ |
244+
| Create custom charts | `charts:create` | ✅ | ✅ | ❌ |
245+
246+
### Evaluation and Testing
247+
248+
| Action | Required Permission | Workspace Admin | Workspace User | Workspace Viewer |
249+
|--------|---------------------|:---------------:|:--------------:|:----------------:|
250+
| Create a dataset | `datasets:create` | ✅ | ✅ | ❌ |
251+
| Upload examples | `datasets:update` | ✅ | ✅ | ❌ |
252+
| Run an experiment | `datasets:update`, `projects:create`, `runs:create` | ✅ | Partial* | ❌ |
253+
| View experiment results | `datasets:read` | ✅ | ✅ | ✅ |
254+
| Delete a dataset | `datasets:delete` | ✅ | ❌ | ❌ |
255+
| Share dataset publicly | `datasets:share` | ✅ | ❌ | ❌ |
256+
| Create annotation queue | `annotation-queues:create` | ✅ | ✅ | ❌ |
257+
| Review runs in queue | `annotation-queues:update` | ✅ | ✅ | ❌ |
258+
259+
*Workspace Users cannot create projects, so they cannot run experiments that create new projects.
260+
261+
### Prompts and Hub
262+
263+
| Action | Required Permission | Workspace Admin | Workspace User | Workspace Viewer |
264+
|--------|---------------------|:---------------:|:--------------:|:----------------:|
265+
| Create a prompt | `prompts:create` | ✅ | ✅ | ❌ |
266+
| View prompts | `prompts:read` | ✅ | ✅ | ✅ |
267+
| Update/commit prompt | `prompts:update` | ✅ | ✅ | ❌ |
268+
| Delete a prompt | `prompts:delete` | ✅ | ✅ | ❌ |
269+
| Fork a prompt | `prompts:create` | ✅ | ✅ | ❌ |
270+
| Make prompt public | `prompts:share` | ✅ | ✅ | ❌ |
271+
272+
### Automation
273+
274+
| Action | Required Permission | Workspace Admin | Workspace User | Workspace Viewer |
275+
|--------|---------------------|:---------------:|:--------------:|:----------------:|
276+
| Create run rule | `rules:create` | ✅ | ✅ | ❌ |
277+
| View rules | `rules:read` | ✅ | ✅ | ✅ |
278+
| Update rule | `rules:update` | ✅ | ✅ | ❌ |
279+
| Delete rule | `rules:delete` | ✅ | ✅ | ❌ |
280+
| Create alert rule | `runs:read` | ✅ | ✅ | ✅ |
281+
282+
### Workspace Management
283+
284+
| Action | Required Permission | Workspace Admin | Workspace User | Workspace Viewer |
285+
|--------|---------------------|:---------------:|:--------------:|:----------------:|
286+
| View workspace info | `workspaces:read` | ✅ | ✅ | ✅ |
287+
| Update workspace settings | `workspaces:manage` | ✅ | ❌ | ❌ |
288+
| Add workspace members | `workspaces:manage` | ✅ | ❌ | ❌ |
289+
| Remove workspace members | `workspaces:manage` | ✅ | ❌ | ❌ |
290+
| Create API keys | `workspaces:manage` | ✅ | ❌ | ❌ |
291+
| Manage secrets | `workspaces:manage` | ✅ | ❌ | ❌ |
292+
| Manage tags | `workspaces:manage` | ✅ | ❌ | ❌ |
293+
| Delete workspace | `workspaces:manage` | ✅ | ❌ | ❌ |
294+
295+
### Organization Management
296+
297+
| Action | Required Permission | Org Admin | Org User | Org Viewer |
298+
|--------|---------------------|:---------:|:--------:|:----------:|
299+
| View organization info | `organization:read` | ✅ | ✅ | ✅ |
300+
| Create workspace | `organization:manage` | ✅ | ❌ | ❌ |
301+
| Manage billing | `organization:manage` | ✅ | ❌ | ❌ |
302+
| Invite org members | `organization:manage` | ✅ | ❌ | ❌ |
303+
| Configure SSO | `organization:manage` | ✅ | ❌ | ❌ |
304+
| Create custom roles | `organization:manage` | ✅ | ❌ | ❌ |
305+
| Create personal access tokens | `organization:pats:create` | ✅ | ✅ | ❌ |
306+
| View usage analytics | `organization:read` | ✅ | ✅ | ✅ |
307+
308+
## Custom Roles
309+
310+
<Info>Creating custom roles is available for organizations on the Enterprise plan.</Info>
311+
312+
Organization Admins can create custom roles with specific combinations of permissions tailored to their organization's needs.
313+
314+
### Creating Custom Roles
315+
316+
Custom roles are created at the organization level and can be assigned to users in any workspace within that organization.
317+
318+
**Steps**:
319+
1. Navigate to Organization Settings > Roles
320+
2. Click "Create Custom Role"
321+
3. Select the permissions to include in the role
322+
4. Assign the custom role to users in specific workspaces
323+
324+
### Custom Role Limitations
325+
326+
- Custom roles can only be created and managed by Organization Admins
327+
- Custom roles are organization-specific (not transferable between organizations)
328+
- Each custom role can have any combination of workspace-level permissions
329+
- Custom roles cannot have organization-level permissions
330+
- Users can have different roles (including custom roles) in different workspaces
331+
332+
## Security Best Practices
333+
334+
1. **Principle of Least Privilege**: Assign users the minimum permissions needed for their role
335+
2. **Regular Audits**: Review user roles and permissions regularly
336+
3. **Workspace Segregation**: Use separate workspaces for development, staging, and production
337+
4. **API Key Management**:
338+
- Use workspace-level API keys with appropriate scopes
339+
- Rotate API keys regularly
340+
- Never share API keys across environments
341+
5. **SSO Configuration**: Enable SSO for centralized authentication and easier offboarding
342+
6. **Custom Roles**: Create custom roles for specialized use cases rather than over-granting permissions
343+
344+
## Additional Resources
345+
346+
- [LangSmith Authentication Guide](https://docs.smith.langchain.com/authentication)
347+
- [API Keys Documentation](https://docs.smith.langchain.com/api-keys)
348+
- [Managing Workspaces](https://docs.smith.langchain.com/workspaces)
349+
- [Organization Settings](https://docs.smith.langchain.com/organization)
350+
351+
*Last Updated: October 2025*

0 commit comments

Comments
 (0)