Overview

This overview covers topics related to managing users, organizations, workspaces, and applications within LangSmith.

Resource hierarchy

Organizations

An organization is a logical grouping of users within LangSmith that defines shared settings applying across all of its workspaces. These settings govern organization-wide concerns rather than individual projects within a workspace. Common organization-level configurations include user management, single sign-on (SSO), OAuth provider configuration, custom role creation, billing, and usage tracking. Typically, there is one organization per company. An organization can have multiple workspaces. For more details, see the setup guide.

When you log in for the first time, a personal organization will be created for you automatically. If you’d like to collaborate with others, you can create a separate organization and invite your team members to join. There are a few important differences between your personal organization and shared organizations:

Feature	Personal	Shared
Maximum workspaces	1	Variable, depending on plan (see pricing page
Collaboration	Cannot invite users	Can invite users
Billing: paid plans	Developer plan only	All other plans available

Workspaces

Workspaces were formerly called Tenants. Some code and APIs may still reference the old name for a period of time during the transition.

A workspace is a logical grouping of users and resources within an organization. Workspaces are commonly used to isolate teams or business units, providing separation between projects and their associated resources. A workspace separates trust boundaries for resources and access control. Users are granted permissions at the workspace level, which determine their access to resources in that workspace, including tracing projects, datasets, annotation queues, and prompts. For details on setup, see the setup guide and for details on permissions see Workspaces (RBAC).

We recommend creating a separate workspace for each team within your organization. To organize resources even further, you can use Applications to group resources within a workspace. For guidance on different workspace organization models based on your team’s isolation requirements, refer to Workload isolation.

Applications

An application is a logical grouping of resources within a workspace. Applications are often agents, but you can use them for any project within a team. Applications keep the UI organized by only surfacing the resources associated with the application currently in context.

Applications are built on top of resource tags and can be used to control resource access using ABAC.

Switch applications from the main navigation sidebar in the LangSmith UI. Use the Application dropdown at the top of the sidebar to select an application.

Any resource can be created without being tagged to an application. These resources will be visible when the All applications option is selected.

Resources

Resources are the concrete entities used to build, run, and observe applications and agents, such as tracing projects, prompts, datasets, and deployments. Resources are scoped to a specific application.

Additional info

The following diagram explains the relationship between organizations, workspaces, applications, and resources:

See the table below for details on which features are available in which scope(s):

Resource/Setting	Scope
Trace Projects	Workspace or Application
Annotation Queues	Workspace or Application
Deployments	Workspace or Application
Datasets & Experiments	Workspace or Application
Prompts	Workspace or Application
Resource Tags	Workspace
API Keys	Workspace
Settings including Secrets, Feedback config, Models, Rules, and Shared URLs	Workspace
User management: Invite User to Workspace	Workspace
RBAC: Assigning Workspace Roles	Workspace
Data Retention, Usage Limits	Workspace*
Plans and Billing, Credits, Invoices	Organization
User management: Invite User to Organization	Organization**
Adding Workspaces	Organization
Assigning Organization Roles	Organization
RBAC: Creating/Editing/Deleting Custom Roles	Organization

* Data retention settings and usage limits will be available soon for the organization level as well ** Self-hosted installations may enable workspace-level invites of users to the organization via a feature flag. See the self-hosted user management docs for details.

Resource tags

Resource tags allow you to further segregate resources within a workspace for use with ABAC. Each tag is a key-value pair that you can assign to a resource.

LangSmith resource tags are very similar to tags in cloud services like AWS.

Navigate to Settings in the LangSmith UI to select the Resource tags page in the sidebar.

User management and RBAC

Users

A user is a person who has access to LangSmith. Users can be members of one or more organizations and workspaces within those organizations.

Organization members are managed on the Settings page under Members and roles.

And workspace members are managed on the Workspaces page under Settings.

API keys

We ended support for legacy API keys prefixed with ls__ on October 22, 2024 in favor of personal access tokens (PATs) and service keys. We require using PATs and service keys for all new integrations. API keys prefixed with ls__ will no longer work as of October 22, 2024.

Expiration dates

When you create an API key, you have the option to set an expiration date. Adding an expiration date to keys enhances security and minimizes the risk of unauthorized access. For example, you may set expiration dates on keys for temporary tasks that require elevated access.

By default, keys never expire. Once expired, an API key is no longer valid and cannot be reactivated or have its expiration modified.

Personal access tokens (PATs)

Personal Access Tokens (PATs) are used to authenticate requests to the LangSmith API. They are created by users and scoped to a user. The PAT will have the same permissions as the user that created it. We recommend not using these to authenticate requests from your application, but rather using them for personal scripts or tools that interact with the LangSmith API. If the user associated with the PAT is removed from the organization, the PAT will no longer work.

PATs are prefixed with lsv2_pt_

Service keys

Service keys are similar to PATs, but are used to authenticate requests to the LangSmith API on behalf of a service account. Only admins can create service keys. We recommend using these for applications / services that need to interact with the LangSmith API, such as LangGraph agents or other integrations. Service keys may be scoped to a single workspace, multiple workspaces, or the entire organization, and can be used to authenticate requests to the LangSmith API for whichever workspace(s) it has access to.

Service keys are prefixed with lsv2_sk_

Use the X-Tenant-Id header to specify the target workspace.

• When using PATs: If this header is omitted, requests will run against the default workspace associated with the key.
• When using organization-scoped service keys: You must include the X-Tenant-Id header when accessing workspace-scoped resources. Without it, the request will fail with a 403 Forbidden error.

To see how to create a service key or Personal Access Token, see the setup guide

Organization roles

Organization roles are distinct from the Enterprise feature workspace RBAC and are used in the context of multiple workspaces. Your organization role determines your workspace membership characteristics and your organization-level permissions.

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

The Organization User and Organization Viewer roles are only available in organizations on Plus and Enterprise plans. In Developer organizations (single workspace), all users are assigned the Organization Admin role by default.

See security settings for instructions on how to disable PAT creation for the entire organization.

For more information on setting up organizations and workspaces, refer to the organization setup guide for more information.

The following table provides an overview of organization level permissions:

	Organization Viewer	Organization User	Organization Admin
View organization configuration	✅	✅	✅
View organization roles	✅	✅	✅
View organization members	✅	✅	✅
View data retention settings	✅	✅	✅
View usage limits	✅	✅	✅
Create personal access tokens (PATs)	❌	✅	✅
Admin access to all workspaces	❌	❌	✅
Manage billing settings	❌	❌	✅
Create workspaces	❌	❌	✅
Create, edit, and delete organization roles	❌	❌	✅
Invite new users to organization	❌	❌	✅
Delete user invites	❌	❌	✅
Remove users from an organization	❌	❌	✅
Update data retention settings	❌	❌	✅
Update usage limits	❌	❌	✅

For a comprehensive list of required permissions along with the operations and roles that can perform them, refer to the Organization and workspace reference.

Workspace roles (RBAC)

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. Other plans default to using the Admin role for all users.

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:

• Workspace Admin has full access to all resources within the workspace.
• Workspace Editor has full permissions except for workspace management (adding/removing users, changing roles, configuring service keys).
• 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.

You can manage roles under Organization Settings > Members and roles and select the Roles tab.

• For comprehensive documentation on roles and permissions, refer to the Role-based access control guide.
• For more details on assigning and creating roles, refer to the User Management guide.
• For a comprehensive list of required permissions along with the operations and roles that can perform them, refer to the Organization and workspace reference.

Best practices

Environment separation

Use resource tags to organize resources by environment using the default tag key Environment and different values for the environment (e.g., dev, staging, prod). We do not recommend using separate workspaces for environment separation because resources cannot be shared across workspaces, which would prevent you from promoting resources (like prompts) between environments.

Resource tags vs. commit tags for prompt management

While both types of tags can use environment terminology like dev, staging, and prod, they serve different purposes:

• Resource tags (Environment: prod): Use these to organize and filter resources across your workspace. Apply resource tags to tracing projects, datasets, and other resources (including prompts) to group them by environment, which enables filtering in the UI.
• Commit tags (prod tag): Use these to manage which prompt version your code references. Commit tags are labels that point to specific commits in a prompt’s history. When your code pulls a prompt by tag name (e.g., client.pull_prompt("prompt-name:prod")), it retrieves whichever commit that tag currently points to. To promote a prompt from staging to prod, move the commit tag to point to the desired version.

Resource tags organize which resources belong to an environment. Commit tags let you control which version of a prompt your code references without changing the code itself.

Additional resources

• Release policy: Learn about the self-hosted release channels, cadence, and version numbering.

---

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

Edit this page on GitHub or file an issue.