Role-based access control

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.

Overview

LangSmith uses a two-tier RBAC system:

• Workspace-level permissions: Control access to resources within a specific workspace (projects, datasets, runs, etc.)
• Organization-level permissions: Control access to organization-wide settings, billing, member management, and workspace creation

Each user can have:

• One organization role that applies across the entire organization
• One workspace role per workspace they’re a member of

Additionally, organizations can create custom roles with granular permission combinations.

Role Types

Workspace roles control what users can do with resources inside a workspace:

Role	Display Name	Description
WORKSPACE_ADMIN	Admin	Full permissions for all resources and ability to manage workspace
WORKSPACE_USER	User	Full permissions for most resources, cannot manage workspace settings or delete certain resources
WORKSPACE_VIEWER	Viewer	Read-only access to all workspace resources

Organization roles control organization-wide capabilities:

Role	Display Name	Description
ORGANIZATION_ADMIN	Organization Admin	Full permissions to manage organization configuration, users, billing, and workspaces
ORGANIZATION_USER	Organization User	Read access to organization information and ability to create personal access tokens
ORGANIZATION_VIEWER	Organization Viewer	Read-only access to organization information

Workspace Roles

Workspace Admin (WORKSPACE_ADMIN)

Description: Default role with full permissions for all resources and ability to manage workspace.

All Permissions:

• All create, read, update, delete, and share permissions for all resource types
• Workspace management capabilities

Workspace User (WORKSPACE_USER)

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 (WORKSPACE_VIEWER)

Description: Read-only access to all workspace resources.

Permissions: Read-only access to all resource types.

Organization Roles

Organization Admin (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
• 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

Organization User (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 (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

Common Operations by Role

This section shows common user workflows and required permissions. For a complete list of all operations, see the Workspace Operations Reference.

Tracing and Monitoring

Action	Required Permission	Workspace Admin	Workspace User	Workspace Viewer
Send traces from SDK	runs:create	✅	✅	❌
View traces	runs:read	✅	✅	✅
Create a project	projects:create	✅	❌	❌
View project dashboard	projects:read	✅	✅	✅
Share a trace publicly	runs:share	✅	✅	❌
Delete traces	runs:delete	✅	❌	❌
Add feedback to a run	feedback:create	✅	✅	❌
View feedback	feedback:read	✅	✅	✅
Create custom charts	charts:create	✅	✅	❌

Evaluation and Testing

Action	Required Permission	Workspace Admin	Workspace User	Workspace Viewer
Create a dataset	datasets:create	✅	✅	❌
Upload examples	datasets:update	✅	✅	❌
Run an experiment	datasets:update, projects:create, runs:create	✅	Partial*	❌
View experiment results	datasets:read	✅	✅	✅
Delete a dataset	datasets:delete	✅	❌	❌
Share dataset publicly	datasets:share	✅	❌	❌
Create annotation queue	annotation-queues:create	✅	✅	❌
Review runs in queue	annotation-queues:update	✅	✅	❌

*Workspace Users cannot create projects, so they cannot run experiments that create new projects.

Prompts and Hub

Action	Required Permission	Workspace Admin	Workspace User	Workspace Viewer
Create a prompt	prompts:create	✅	✅	❌
View prompts	prompts:read	✅	✅	✅
Update/commit prompt	prompts:update	✅	✅	❌
Delete a prompt	prompts:delete	✅	✅	❌
Fork a prompt	prompts:create	✅	✅	❌
Make prompt public	prompts:share	✅	✅	❌

Automation

Action	Required Permission	Workspace Admin	Workspace User	Workspace Viewer
Create run rule	rules:create	✅	✅	❌
View rules	rules:read	✅	✅	✅
Update rule	rules:update	✅	✅	❌
Delete rule	rules:delete	✅	✅	❌
Create alert rule	runs:read	✅	✅	✅

Workspace Management

Action	Required Permission	Workspace Admin	Workspace User	Workspace Viewer
View workspace info	workspaces:read	✅	✅	✅
Update workspace settings	workspaces:manage	✅	❌	❌
Add workspace members	workspaces:manage	✅	❌	❌
Remove workspace members	workspaces:manage	✅	❌	❌
Create API keys	workspaces:manage	✅	❌	❌
Manage secrets	workspaces:manage	✅	❌	❌
Manage tags	workspaces:manage	✅	❌	❌
Delete workspace	workspaces:manage	✅	❌	❌

Organization Management

Action	Required Permission	Org Admin	Org User	Org Viewer
View organization info	organization:read	✅	✅	✅
Create workspace	organization:manage	✅	❌	❌
Manage billing	organization:manage	✅	❌	❌
Invite org members	organization:manage	✅	❌	❌
Configure SSO	organization:manage	✅	❌	❌
Create custom roles	organization:manage	✅	❌	❌
Create personal access tokens	organization:pats:create	✅	✅	❌
View usage analytics	organization:read	✅	✅	✅

Custom Roles

Creating custom roles is available for organizations on the Enterprise plan.

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

Custom Role Limitations

• 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

Security Best Practices

1. Principle of Least Privilege: Assign users the minimum permissions needed for their role
2. Regular Audits: Review user roles and permissions regularly
3. Workspace Segregation: Use separate workspaces for development, staging, and production
4. API Key Management:
   • Use workspace-level API keys with appropriate scopes
   • Rotate API keys regularly
   • Never share API keys across environments
5. SSO Configuration: Enable SSO for centralized authentication and easier offboarding
6. Custom Roles: Create custom roles for specialized use cases rather than over-granting permissions

Additional Resources

• LangSmith Authentication Guide
• API Keys Documentation
• Managing Workspaces
• Organization Settings

Last Updated: October 2025

---

Edit the source of this page on GitHub.

Connect these docs programmatically to Claude, VSCode, and more via MCP for real-time answers.