Resource hierarchy
LangSmith organizes access and data in four levels. An organization contains workspaces. Each workspace contains agents. Agents organize your traces by environment and group the resources you work with, such as datasets and prompts. Self-hosted LangSmith groups resources by application instead of agent. For details, see Self-hosted workspaces. The following diagram shows the relationship between organizations, workspaces, agents, environments, and resources: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 the agents and resources 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 configuration details, see Set up an organization. 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:Workspaces
Workspaces were formerly called Tenants. Some code and APIs may still reference the old name for a period of time during the transition.
Agents
An agent is a logical grouping of resources within a workspace, one level below the workspace itself. The grouping keeps the UI organized by surfacing only the resources associated with the agent currently in context. An agent’s traces divide further into environments drawn from a fixed set of four. Select an agent from the agent switcher in the top bar, or select All agents. For more information, see Navigate agents. LangSmith links traces to an agent through the agent’s environments, and links datasets, prompts, annotation queues, and deployments to an agent with the reservedAgent resource tag key.
Tracing pages require you to select an agent. Datasets, prompts, annotation queues, and deployments can exist without an agent. Selecting All agents shows these unlinked resources along with every agent’s resources. Selecting a specific agent shows only that agent’s resources.
Resources
Resources are the concrete entities used to build, run, and observe agents. Examples include prompts, datasets, annotation queues, and deployments. Resources can be scoped to a specific agent.Where settings live
See the table below for details on which features are available in which scope(s):* 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. For details, refer to the self-hosted user management docs.
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.Separate environments
An environment is a stage in your release process, such as development, staging, or production. Agents have environments built in, drawn from a fixed set of four. An agent divides its traces across them, so no tagging convention is required. For more information, see Agent environments. Self-hosted LangSmith separates environments with resource tags instead. For details, see Self-hosted workspaces. In either case, avoid using separate workspaces for environment separation, because resources cannot be shared across workspaces, which prevents you from promoting resources such as prompts between environments.Resource tags vs. commit tags for prompt managementWhile 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 resources across your workspace. Apply resource tags to tracing projects, datasets, and other resources (including prompts) to group them by environment. - Commit tags (
prodtag): 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 fromstagingtoprod, move the commit tag to point to the desired version.
Self-hosted workspaces
Self-hosted LangSmith uses project-based workspaces, which group resources by application rather than agent. An application can group any project within a team. Select one from the Application dropdown at the top of the sidebar, or select All applications to see every resource in the workspace. Project-based workspaces separate environments with resource tags: the default tag keyEnvironment, with a different value per environment (for example, dev, staging, prod).
To check which type of workspace you have, see How agent-based workspaces differ.
Users and roles
This section covers who can access LangSmith and what they can do: users, the three types of API keys, and the roles that grant permissions.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. Manage members from the Settings page, which has separate sections for the organization and the workspace:- Organization > Members: Manage members of the organization.
- Workspace > Members: Manage members of the current workspace.
API keys
LangSmith API keys authenticate requests to LangSmith. They are separate from the model provider keys, such as OpenAI or Anthropic keys, that your application uses to call models.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. 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. PATs are prefixed withlsv2_pt_
Members can deactivate, reactivate, or delete their own PATs. Organization Admins and Organization Operators can also list, deactivate, reactivate, and delete any member’s PAT.
Deactivating a token stops authentication but keeps its record, owner, and last use visible with a Deactivated badge. Deactivation is reversible; deletion permanently removes the record. Reactivation preserves the original expiration date and is unavailable once that date has passed. Because authentication results are cached, these changes take effect within a minute rather than instantly.
For the steps and authentication-cache timing, refer to Deactivate or delete a personal access token.
Service keys
Service keys are similar to PATs, but are used to authenticate requests to the LangSmith API on behalf of a service account. Organization Admins can create any service key. Organization Operators and Organization Users can create workspace-scoped service keys in workspaces where their role grantsworkspaces:manage-keys, such as Workspace Admin. For the full breakdown, see API keys operations. We recommend using service keys for applications or 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. They 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_.
Service keys can only be deleted, not deactivated.
To create any type of API key, see Create an account and API key.
Tracing keys
Tracing keys are organization-owned credentials with fixed permissions to submit traces and create projects in selected workspaces. They do not grant access to stored traces, experiments, saved views, or administration. Tracing keys use thelsv2_tr_ prefix. Their scope is fixed at creation, and they remain valid when the creator leaves the organization. They follow service-key expiry limits. For creation permissions, scope limits, and deletion rules, refer to Tracing keys.
Roles
Each user has one organization role, which applies across the organization. On Enterprise plans, each user also has one workspace role in every workspace they belong to. Manage both in Settings > Roles. For more information, see Role-based access control.Organization roles
Your organization role determines your organization-level permissions and your workspace membership. Organization roles are distinct from workspace roles (an Enterprise feature), and apply across all workspaces in the organization. Each organization role affects workspace membership as follows:- The role of Organization Admin grants a user full access to manage all organization configuration, users, billing, and workspaces.
- An Organization Admin has
Adminaccess to all workspaces in an organization.
- An Organization Admin has
- The role of Organization Operator grants a user management access to workspaces and non-admin users for day-to-day operations, without admin-level privileges such as managing Organization Admins.
- An Organization Operator is added only to the workspaces they create or are invited to.
- The role of Organization User grants a user permission to read organization information. However, they 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.
- The role of Organization Viewer is equivalent to Organization User, but a user with this role cannot create Personal Access Tokens. Self-hosted installations require Helm chart version 0.11.25 or later for this role.
- The role of Organization Restricted grants a user access to their assigned workspaces without organization-wide read access, so the user cannot list organization members. Workspace-scoped service keys can also hold this role.
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.
* Organization Operators cannot invite, remove, or delete invites for Organization Admins.
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 (Role-Based Access Control) 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.
- Workspace Admin has full access to all resources within the workspace.
- Workspace Editor can create, edit, and delete most resources, but cannot delete runs, change workspace settings, or manage workspace members.
- Workspace Viewer has read-only access to all resources within the workspace.
Usage and billing
For trace retention periods, rate limits, and usage limits, see Usage and billing. To manage invoices and spend, see Manage billing.See also
- Release policy: Learn about the self-hosted release channels, cadence, and version numbering.
Connect these docs to your agent of choice via MCP for real-time answers.

