Environment=Development.
Access policies can match two kinds of attributes:
- Resource tags (
resource_tag_key): The resource tags on projects, datasets, prompts, and other workspace resources. - Root run metadata (
root_run_metadata): The metadata on the root run of each trace. Use it to control which traces a user can read within a project. For details, refer to Control trace access with root run metadata.
ABAC is available on Enterprise plans. If you are interested in this feature, contact our sales team. Other plans default to using the Admin role for all users.
Before you begin
You must have:- ABAC enabled for your organization: On LangSmith Cloud, ABAC is part of the Enterprise plan. On a self-hosted deployment, enable ABAC first.
- Permission to manage policies: Creating, editing, or deleting a policy requires
organization:access-control:manage, which Organization Admins and Organization Operators hold. - Resource tags: For tag-based conditions, set up resource tags in your workspace. Policies that use only root run metadata do not require resource tags.
- API credentials: To manage policies with the API, use a personal access token (PAT) from a user with
organization:access-control:manage, or an organization-scoped service key with Organization Admin permissions. Send requests to your API URL. For LangSmith Cloud, find the API URL for your region in Regional storage. For a self-hosted deployment, usehttps://<your-langsmith-domain>/api.
Enable ABAC on a self-hosted deployment
ABAC on a self-hosted deployment requires Helm chart 0.11.28 or later (application version 0.12.1). After you upgrade, use one of the following options to enable it:-
Enable for a specific organization: Run the following against your LangSmith PostgreSQL database, replacing
<organization_id>with the ID copied from the organization settings page in the UI: -
Enable for all organizations: Add the following environment variable to
commonEnvin yourvalues.yaml:This environment variable has no effect on personal organizations because RBAC is not enabled for personal organizations.
Access policy structure
An access policy is a JSON object that sets an effect, one or more condition groups, and the roles the policy applies to:Effect
Theeffect determines what happens when conditions match:
allow: Grant access when conditions match.deny: Block access when conditions match.
Deny policies always take precedence. If both an allow and deny policy match, access is denied.
Condition groups
Thecondition_groups array contains one or more condition groups. LangSmith evaluates multiple condition groups with OR logic. If any group matches, the policy applies.
Each condition group has the following fields:
permission: The permission this group applies to.resource_type: The resource type to match.conditions: An array of conditions, evaluated with AND logic within the group.
Resource types and permissions
Some resource types are evaluated differently:
- Runs: Runs do not have their own tags. Run permissions (
runs:read,runs:read-inputs,runs:read-outputs,runs:create,runs:share,runs:delete) are evaluated against the parent project’s tags. For how the input and output permissions affect responses, refer to Control access to run inputs and outputs. - Agent environments: In an agent-based workspace, a tracing project is one environment of an agent. A
projectcondition group applies to each environment separately rather than to the agent as a whole. - Dataset clones: Cloning copies examples from a source dataset to a target dataset. LangSmith checks
datasets:clonetwice, once against each dataset’s tags. A policy must grantdatasets:cloneon both datasets.
Conditions
Each condition in theconditions array has the following fields:
attribute_name:resource_tag_keyto match resource tags, orroot_run_metadatato match root run metadata.attribute_key: The tag key or metadata key to match, such asEnvironmentorApplication.operator: The comparison operator.attribute_value: The value to compare against.
resource_tag_key conditions. root_run_metadata conditions support only equals. For their rules, refer to Control trace access with root run metadata.
Operators
_if_exists variants
Each operator has an _if_exists variant that matches by default when the tag key is absent, or evaluates the condition normally when the tag exists:
Roles
Therole_ids array specifies which workspace roles the policy applies to. When a user with that role accesses a resource, the policy conditions are evaluated.
Policies can be attached to workspace roles (built-in or custom) when creating the policy, or attached later in the UI or with the API.
Policies can also be attached to user groups. A user group’s policies apply to its members in the workspaces the user group can access.
To provision users into roles automatically from your identity provider, see SCIM.
Managing access policies
Manage access policies in your organization settings with the visual editor, or with the LangSmith API. Both requireorganization:access-control:manage.
Create an access policy in the UI
In the visual editor, each rule corresponds to a condition group. To create an access policy:- Go to Settings, and select Organization. Then go to Permissions > Access Policies. In some versions of the settings page, this page is listed as ABAC under Access and Security.
- Under ABAC, select the Policies tab, and then click Create Policy.
- Enter a Name and, optionally, a Description.
- Set Effect to Allow or Deny.
- Click Add rule, and then select a Resource Type and Permission.
- Click Add condition, and choose the condition source:
- Resource tag: Enter a Tag Key, operator, and Tag Value. Create the resource tags before using them in a policy.
- Root-run metadata: First select Project for Resource Type and
runs:readfor Permission. Enter a Metadata Key and a Metadata Value. The operator is fixed toequals, and Metadata Value is prefilled with${user.ls_user_id}, which matches the current user. Replace it with a literal value to match a fixed value instead. For requirements and an example, refer to Create a root run metadata policy in the UI.
- Click Save condition, add any more conditions, and then click Add rule to return to the policy editor. All conditions within a rule must match, and multiple rules use OR logic.
- (Optional) Attach the policy to roles. A policy has no effect until you attach it to a role or user group. In the dialog under Roles, click Add role. Select the workspace roles the policy applies to, and click Add roles. You can inspect each role’s permissions before adding it. You can also attach a policy to roles later.
- To finish, click Create policy.
Edit or delete an access policy
On the Policies tab, use the icons in a policy’s Actions column. To edit a policy, including attaching or detaching roles, click its edit icon, make your changes, and click Save changes. To delete a policy, click its delete icon, enter the policy’s name to confirm, and click Delete.Attach policies to user groups
User Groups do not create policies. They attach existing ones:- Attaching a policy to a user group requires
organization:user-groups:manage-policies. - A Workspace Admin can attach an existing policy to a user group as a workspace-only policy in their workspace, with
workspaces:user-groups:manage-policies.
How ABAC works with RBAC
RBAC permissions and ABAC policies are both considered when determining access to resources:- ABAC deny policies override RBAC permissions.
- ABAC allow policies can grant access even without RBAC permissions.
- If no ABAC policies match, the system falls back to RBAC.
When both RBAC and ABAC are enabled, each request resolves as follows:
Control access to run inputs and outputs
runs:read controls whether a user can see a run. runs:read-inputs and runs:read-outputs control whether the user can see the run’s inputs and outputs. Message and trajectory views require both.
Policies for these permissions use resource_type: "project" and evaluate the tags of each run’s parent project. Use them to hide inputs, outputs, or both in sensitive projects while leaving other projects in the workspace unchanged. RBAC and ABAC combine for these permissions the same way they do for any other permission, as described in How ABAC works with RBAC. For an example, refer to Hide run inputs and outputs in sensitive projects.
Control trace access with root run metadata
Aroot_run_metadata condition limits which traces a user can read in a project, based on a key in each trace’s root run metadata. Use it to hide some traces in a project, or to show users only the traces labeled for them, without moving traces into separate projects.
A root_run_metadata condition is valid only in a condition group with permission: "runs:read" and resource_type: "project". It accepts the following fields:
attribute_key: A top-level key in the root run metadata. Nested keys are not supported, so the key cannot contain..operator:equalsonly. The match is case sensitive.attribute_value: The value to match, or the placeholder${user.ls_user_id}. The placeholder matches thels_user_idof the user making the request. Retrieve this value fromGET /auth/public. Use the response’sls_user_idfield, which is distinct fromuser_idor a user object’sid.
attribute_key nor attribute_value can contain a double quote or a backslash, and each is limited to 255 bytes. A value that starts with ${ must be exactly ${user.ls_user_id}.
A condition group can combine root_run_metadata conditions with resource_tag_key conditions. The tag conditions select the projects the group applies to, and the metadata conditions select the traces in those projects. All conditions in a group must match.
Conditions evaluate only the root run, so all runs in a trace are visible or hidden together. Set the metadata key and value on the root run before ingestion. Root run metadata is immutable after ingestion, so you cannot add or change it later to make a trace match a policy. For how to add metadata, refer to Add metadata and tags to traces.
Create a root run metadata policy in the UI
The Root-run metadata option requires the Project resource type and the
runs:read permission. Root run metadata conditions must also be enabled for your organization. This option is not available in the self-hosted UI; on self-hosted installations, create root run metadata policies with the API instead. On cloud, if the option is disabled after you select that resource type and permission, contact your LangChain representative.source set to customer.
To create the policy:
- Open the policy editor, as in steps 1 and 2 of Create an access policy in the UI. Enter
Hide Customer Tracesfor Name and set Effect to Deny. - Click Add rule. Select Project for Resource Type and
runs:readfor Permission. - Click Add condition and change the source from Resource tag to Root-run metadata.
- Enter
sourcefor Metadata Key. The operator is fixed toequals. Replace the prefilled${user.ls_user_id}in Metadata Value withcustomer. - Click Save condition, then Add rule.
- Under Roles, add the workspace roles that should not see these traces. Click Create policy.
allowed_ls_user_id and keep the prefilled ${user.ls_user_id} for Metadata Value. Attach the policy to a role without runs:read. If the role has runs:read, its RBAC permission still grants access to other traces.
How metadata conditions combine with RBAC
Metadata conditions follow the same precedence as other policies: deny policies apply first, then RBAC, then allow policies.- Deny policies: A deny policy with metadata conditions hides the matching traces instead of blocking the whole project. The user keeps access to the other traces in the project. When several deny policies apply, a trace that matches any of them is hidden.
- Allow policies: An allow policy with metadata conditions grants
runs:readon the matching traces only. When several allow policies apply, the user can read a trace that matches any of them. - RBAC: If the user’s role grants
runs:read, the user can read every trace that a deny policy does not hide, and allow policies have no effect. To limit a role to the traces an allow policy matches, removeruns:readfrom the role.
ls_user_id, so conditions using ${user.ls_user_id} do not match. Requests authenticated with a personal access token (PAT) or a signed-in browser session have the user’s ls_user_id. For details on PATs and service keys, refer to API keys.
Responses under metadata conditions
When metadata conditions apply to a user in a project, LangSmith filters that user’s reads in the project to the traces they can see:- Run lists, trace lists, and run analytics omit hidden traces.
- Requesting a hidden trace or one of its runs by ID returns
404 Not Found. This includes downloading the trace and opening its messages or trajectory. - The project list omits run and feedback statistics for the project.
Example scenarios
1. Restrict annotators to their datasets
Allow annotators to only access datasets tagged for their annotation group:2. Block sensitive data
Deny access to datasets containing PII. Since deny policies override allow policies, this blocks access even for users with RBAC permissions:3. Application-based access with wildcards
Allow engineers to access projects for any application in the “chatbot” family using glob patterns:4. Client and purpose isolation (AND logic)
Grant access only if both conditions are met - dataset is for training AND belongs to a specific client:5. Client data plus resources without a Client tag using _if_exists
Consultants do not have RBAC datasets:read permission, but this policy grants them access to datasets tagged Client=Acme-Corp, as well as datasets that do not have a Client tag at all. Datasets tagged with a different client (e.g., Client=Other-Corp) remain blocked:
6. Hide run inputs and outputs in sensitive projects
Let users keep browsing runs in projects that contain PII, but hide the runs’ inputs and outputs. Each permission gets its own condition group, and the groups are evaluated with OR logic. Users still needruns:read to see the runs:
7. Hide traces by root run metadata
Hide traces whose root run hassource set to customer, in every project. Users whose role grants runs:read still see all other traces:
8. Show users only the traces labeled for them
Show each user only the traces whose root run hasallowed_ls_user_id set to that user’s LangSmith user ID. Attach this policy to a role that does not grant runs:read, because RBAC permissions take precedence over allow policies:
9. Team traces in production projects
Grant access to traces whose root run hasteam set to payments, only in projects tagged Environment=prod. The tag condition selects the projects, and the metadata condition selects the traces in them:
Tag resources at creation time
When ABAC policies are active, resources are access-controlled based on their tags. To make sure a resource is protected as soon as it is created, you can supply tags directly in the creation request using thetag_value_ids parameter.
This is supported on project, dataset, and prompt creation endpoints (including fork and clone operations). Tags are applied atomically in the same database transaction as resource creation.
For full details and examples, see Tag a resource at creation time in the resource tags guide.
If you rely on the LangSmith SDK to auto-create tracing projects during trace ingestion, the
tag_value_ids parameter is not available on that auto-create path. To ensure ABAC policies apply from the start, pre-create the project via POST /api/v1/sessions with the desired tag_value_ids before starting your trace session.Troubleshooting
Access unexpectedly denied?- Check if a deny policy is matching (deny always takes precedence)
- Check if the user has RBAC permissions or a matching allow policy
- Verify the resource has the expected tag and value
- Deny policies with
_if_existsoperators block resources missing that tag key - For case-sensitive operators (
equals,not_equals), check for case mismatches - With multiple conditions in a group, all must match (AND logic)
- Review RBAC permissions (users may have access via their role)
- Check if an allow policy is too broad (e.g., using wildcards)
_if_existsoperators match resources missing that tag key
- Check that the user’s role grants
runs:read-inputsandruns:read-outputs, or that an allow policy grants them for the run’s project - Check for a deny policy on
runs:read-inputsorruns:read-outputsthat matches the project’s tags - Message and trajectory views return
403 Forbiddenunless both permissions are granted
404 Not Found?
- Check for a deny policy with a
root_run_metadatacondition that matches the trace’s root run metadata - If the user’s access comes from an allow policy with
root_run_metadataconditions, check that the root run has the metadata key and the exact value, including case - Conditions match top-level keys on the root run only, not metadata on child runs
403 Forbidden?
- These surfaces are unavailable in any project where
root_run_metadataconditions apply to the user. For the full list, refer to Responses under metadata conditions
- Confirm the policy is attached to the correct role
- Verify the user has that role in the workspace
- Check that
resource_typeandpermissionmatch the resource being accessed
Connect these docs to your agent of choice via MCP for real-time answers.

