LangSmith Team Workflows: Roles and Access Control

The first time a second engineer joins your LangSmith project, everything gets more complicated. Suddenly the tracing project you set up on your personal account needs to be shared. Your API key is hardcoded in three places and nobody knows which one is yours. The prompt you carefully tuned last week was overwritten by a teammate who did not know you were iterating on it. None of this is a LangSmith problem, exactly. It is a team workflow problem, and LangSmith gives you a specific set of primitives to solve it: organizations, workspaces, roles, API key types, and access controls. This guide walks through how those pieces fit together and how to design langsmith team workflows that scale from two engineers to a whole platform organization without turning access management into a part-time job.

Why Team Structure in LangSmith Matters More Than You Think

LangSmith is not just a dashboard you glance at occasionally. For teams shipping LLM applications seriously, it becomes the system of record for several things at once: every production trace, every evaluation dataset, every prompt version, every annotation a human reviewer has made, and every experiment comparing one model configuration against another. That concentration of value is exactly why access control matters.

Consider what actually lives inside a mature LangSmith setup. Production traces frequently contain user inputs, which can include personal data, internal documents, or customer conversations. Datasets encode your ground truth, the examples your team has decided represent correct behavior. Prompts are, in many LLM products, the closest thing you have to business logic. If any engineer can delete a dataset, overwrite a production prompt, or read traces from a sensitive application, you have a governance gap even if nothing has gone wrong yet.

There is also a velocity argument, not just a safety one. Good team workflows are less about locking people out and more about giving each person an environment where they can move fast without stepping on anyone else. A data scientist iterating on an evaluation should not need to worry about polluting the traces your on-call engineer is using to debug a production incident. Separating concerns with workspaces and roles is what makes that possible.

The teams that struggle with LangSmith at scale are almost always the ones that grew organically from a single personal account, with everyone sharing one API key and one workspace. The teams that thrive spent an afternoon early on deciding who needs access to what. This article is that afternoon, condensed.

Organizations and Workspaces: The Two-Level Hierarchy

LangSmith structures access around two levels: the organization and the workspace. Understanding the distinction is the foundation for everything else.

The organization is the top-level container. It is where billing lives, where your subscription plan is set, and where members are invited to the company account. Organization-level settings govern things that apply across the board, such as who is allowed to create new workspaces and who manages the overall member list. When your company adopts LangSmith, you generally create one organization and invite everyone into it.

Workspaces sit inside the organization, and they are where the actual work happens. A workspace contains its own tracing projects, datasets, experiments, prompts, annotation queues, and dashboards. Resources in one workspace are isolated from resources in another. A member of your organization sees only the workspaces they have been added to, and within each workspace their role determines what they can do.

This two-level model maps naturally onto how companies are structured. The organization mirrors the company or business unit. Workspaces mirror teams, products, or environments. A member can belong to multiple workspaces with different roles in each, which is a detail worth internalizing early: your staff engineer might be an admin of the platform team workspace, a regular member of the search team workspace, and have no access at all to the workspace where the HR chatbot traces live.

One practical implication: because resources do not move fluidly between workspaces, your workspace boundaries are a commitment. Splitting a workspace later means recreating projects, re-uploading datasets, and updating API keys in every service that pointed at the old one. Spend real thought on the boundaries up front, which is exactly what the workspace strategy section below is for.

Within a workspace, LangSmith also offers resource tags as a lighter-weight organizational layer. Tags let you group related resources, for example tagging every project, dataset, and prompt that belongs to a single application, so the workspace can host several related efforts without becoming an undifferentiated pile. Tags organize; workspaces isolate. Use tags when you want findability, and separate workspaces when you want a hard boundary.

Understanding Roles: Who Can Do What

Roles in LangSmith operate at both levels of the hierarchy, and the distinction between organization roles and workspace roles trips up many teams during setup.

At the organization level, the meaningful split is between admins and regular members. Organization admins manage the things that affect everyone: inviting and removing members, configuring billing, creating workspaces, and setting organization-wide policies. Organization admins typically get admin access across workspaces as well, which is why this role should be limited to a small set of people, usually a platform lead and one or two backups. Regular organization members, by contrast, simply have a seat in the organization; what they can actually touch is determined workspace by workspace.

At the workspace level, roles govern day-to-day capability. An admin of a workspace manages its membership and settings in addition to having full access to its resources. Regular members can do the substantive work: create tracing projects, run experiments, build datasets, edit prompts, and process annotation queues. On plans that support role-based access control, you can go further and define finer-grained roles, such as a read-only viewer role for stakeholders who need to see dashboards and traces but should never modify anything, or a role that can annotate traces but cannot delete datasets.

The most useful mental model is to assign roles based on the blast radius of a mistake, not on seniority. Ask, for each person, what is the worst thing they could do accidentally with this level of access, and whether their job requires the capability that makes that accident possible. A product manager reviewing conversation quality does not need dataset deletion rights, so a viewer or annotator-style role fits. An ML engineer running nightly evaluations needs to create experiments and modify datasets, so a full member role fits. Only the people responsible for the workspace itself need admin.

A few role assignments deserve special care. Whoever holds workspace admin can add and remove members, so treat it like production deploy access. And because prompt edits can change production behavior in prompt-driven applications, teams on plans with custom roles often restrict prompt editing more tightly than trace viewing, mirroring how they would review code before merging.

API Keys: Personal Access Tokens and Service Keys

Human access is only half the story. Most interaction with LangSmith happens programmatically: your application sends traces, your CI pipeline runs evaluations, your scripts pull datasets. All of that flows through API keys, and LangSmith distinguishes between two kinds.

A personal access token identifies a specific human. When you create one, actions performed with it are attributed to you and carry your permissions. If you leave the organization or your access is revoked, tokens tied to your identity stop working. That last property is a feature for individual use and a catastrophic failure mode for production systems.

A service key, by contrast, belongs to the workspace rather than to a person. It is the right choice for anything automated: the production application emitting traces, the CI job that runs your evaluation suite on every pull request, the scheduled script that syncs datasets. Service keys survive personnel changes, which is exactly what you want for infrastructure.

The rule that saves teams from painful incidents is simple: personal access tokens for humans, service keys for machines, never the reverse. The classic failure story goes like this: an engineer sets up production tracing during a hack week using their personal token, it works, everyone forgets about it, and eight months later that engineer changes teams and production tracing silently dies. Nobody notices until an incident occurs and the traces everyone expected to inspect simply are not there. Every experienced LLM ops team has either lived this story or narrowly avoided it.

Some operational hygiene practices worth adopting from day one:

• Name every service key after the system that uses it, such as checkout-agent-prod or eval-ci, so an unexplained key is never a mystery.
• Create separate keys per environment. Your staging deployment and production deployment should not share a key, because you want to be able to revoke one without touching the other.
• Store keys in your secret manager, never in code or in shared documents, and inject them through environment variables like LANGCHAIN_API_KEY at deploy time.
• Rotate keys on a schedule and immediately after any suspected exposure, and make rotation cheap by ensuring keys are referenced in exactly one place per service.

Because API keys are scoped to a workspace, your workspace design directly shapes your key management. A service key for the production workspace cannot write to the development workspace, which is a useful guardrail: even a badly misconfigured dev environment cannot pollute production traces.

Designing a Workspace Strategy for Real Teams

There is no single correct workspace layout, but there are two dominant patterns, and most teams end up with a hybrid of them.

The first pattern is workspaces by environment: one workspace for development, one for staging, one for production. The appeal is isolation of data quality. Development traces are noisy, full of half-finished experiments and debugging sessions, and you do not want them anywhere near the traces you use to compute production quality metrics. Environment-based workspaces also let you enforce different access levels per environment: everyone gets full access to dev, most people get read access to production, and only the on-call rotation and platform team get elevated production rights. The downside is duplication, since datasets and prompts you want in all environments must be copied or synced between workspaces.

The second pattern is workspaces by team or product. The search team gets a workspace, the support-bot team gets a workspace, the internal-tools team gets a workspace. This maps cleanly to organizational ownership and keeps each team's resources discoverable, and access control mirrors the org chart. The downside is that development and production data mingle unless you are disciplined with project naming and tags.

The hybrid that works well for mid-sized organizations is team-based workspaces with an environment split only where it matters: each team gets a primary workspace for development and experimentation, and production tracing goes to either a dedicated production workspace per team or a shared production workspace administered by the platform group. That gives you tight control exactly where the sensitive data lives while keeping day-to-day development friction low.

Whichever pattern you choose, write it down. A half-page document stating what workspaces exist, what belongs in each, who approves access, and how service keys are named will prevent the slow drift into chaos that otherwise happens one convenient exception at a time.

Within each workspace, apply the same intentionality to tracing projects. A project per application per environment, with consistent names like support-agent-prod and support-agent-staging, makes filtering trivial and keeps dashboards meaningful. Use resource tags to group everything belonging to one application so that new team members can find the relevant datasets and prompts without asking around.

Collaboration Workflows: Prompts, Datasets, and Annotation Queues

Access control is the skeleton; collaboration workflows are the muscle. Three LangSmith features carry most of the collaborative load, and each has a workflow pattern that works well for teams.

Prompt collaboration is the most immediately visible. LangSmith's prompt hub within a workspace stores prompts with full version history, and every saved change creates a new commit-like version you can inspect and roll back to. The workflow that mature teams converge on treats prompts like code: engineers iterate freely on draft versions, but the application references a specific version or a designated production tag rather than blindly pulling the latest. Promoting a new prompt version to production becomes a deliberate act, ideally done after an evaluation run demonstrates the new version is at least as good as the old one. This one habit eliminates the entire category of incident where someone's experiment becomes production behavior by accident.

Dataset collaboration is quieter but arguably more important, because datasets are how a team agrees on what good looks like. The healthy pattern is to treat dataset curation as a shared, ongoing activity rather than a one-time setup task. Engineers add failing production cases to a dataset as they encounter them, domain experts review and correct expected outputs, and the evaluation suite grows alongside the product. Role-wise, this means your annotators and domain experts need write access to datasets even if they never touch code, which is a good argument for roles that separate data curation rights from resource administration rights.

Annotation queues are LangSmith's mechanism for structured human review, and they are where non-engineering teammates plug into the workflow most naturally. A typical setup routes a sample of production traces, or every trace flagged by an automated evaluator, into a queue. Reviewers work through the queue, scoring responses and leaving feedback, without needing to understand tracing projects or run queries themselves. For this to work smoothly, reviewers need exactly enough access to see and annotate the traces in their queue, which is another place where a restrained role assignment keeps the experience simple for them and safe for you.

The common thread across all three: the collaboration features work best when access follows function. Give each participant the narrowest role that fully covers their actual activity, and the workflows become self-explanatory rather than requiring constant coordination.

Enterprise Controls: RBAC, SSO, and Provisioning

As organizations grow, the manual approach to access management stops scaling, and LangSmith's enterprise-oriented features exist to close that gap.

Custom role-based access control lets you go beyond the built-in roles and define roles with specific permission sets. This is where you build the viewer role for executives, the annotator role for the support team doing quality review, or the operator role that can manage tracing projects but cannot touch datasets. When designing custom roles, resist the temptation to create one role per person. Aim for a small set of roles named after functions, such as viewer, annotator, engineer, and admin, and force yourself to fit people into them. Five well-understood roles beat twenty bespoke ones every time, because the point of roles is that anyone can predict what a role can do from its name.

Single sign-on through your identity provider removes the standalone-password problem and, more importantly, ties LangSmith access to your central identity lifecycle. When someone leaves the company, deactivating them in the identity provider cuts their LangSmith access along with everything else. If your organization handles sensitive data in traces, SSO should be considered a prerequisite for production use, not a nice-to-have.

SCIM-based provisioning takes it a step further by automating membership itself: identity provider groups map to LangSmith access, so joining the ML platform group in your directory automatically grants the corresponding workspace membership, and leaving the group revokes it. This turns access reviews from an archaeology project into a directory query.

For organizations whose compliance posture does not permit sending trace data to a managed cloud at all, LangSmith supports self-hosted deployment, which puts the entire platform, data included, inside your own infrastructure. Self-hosting changes the operational calculus considerably, since your team now runs the platform, but the roles and workspace concepts carry over intact, so the workflow design in this article applies either way.

Even if you are not on an enterprise plan today, it is worth designing your workspace and role conventions as if you will be. Teams that keep clean boundaries early find the upgrade to RBAC and SCIM a formality; teams that let everyone be an admin of everything face a painful untangling.

Common Access Control Mistakes and How to Avoid Them

Certain mistakes appear so consistently across teams adopting LangSmith that they are worth calling out explicitly.

1. Everyone is an admin. It starts innocently, because making someone an admin is the fastest way to unblock them. Six months later, nobody knows who can delete what, and your access model is a flat list of superusers. Fix it by defaulting new members to the least privileged role that lets them work and requiring a reason for elevation.
2. Personal tokens in production. Covered above, but it earns a second mention because it is the single most common LangSmith operational incident. Audit your deployed services once and replace every personal token with a service key; the audit takes an hour and removes a whole failure class.
3. One workspace for everything. When development experiments, production traces, and every team's datasets share one namespace, nothing is discoverable and every permission decision affects everyone. If you are past roughly one team or one product, split.
4. No prompt promotion discipline. If production pulls the latest version of every prompt, then every prompt save is an unreviewed production deploy. Pin versions or use a production tag, and promote deliberately.
5. Untracked key sprawl. Keys created for a quick script, shared in a chat, and never revoked accumulate into a silent attack surface. Keep a simple inventory of service keys, what uses them, and when they were last rotated.
6. Ignoring data sensitivity in trace routing. If one of your applications handles sensitive conversations, decide deliberately who can view its traces, and isolate it in a workspace with a shorter access list. Retroactively discovering that forty people could read those traces is a bad meeting.

None of these fixes are technically difficult. They are all decisions, and the failure mode in every case is simply that nobody made the decision on purpose.

A Rollout Playbook for Your Team

If you are setting up LangSmith for a team right now, here is a concrete sequence that encodes everything above.

1. Create the organization with a shared admin account or a designated platform owner, and add one backup admin immediately. Two admins is the minimum for resilience; keep the list close to that.
2. Sketch your workspace map before creating anything: which teams, which products, which environments deserve isolation. Write the half-page conventions document, including naming schemes for projects and service keys.
3. Create the workspaces and invite members with intentional roles. Default to member, reserve admin for workspace owners, and use viewer-style roles for stakeholders where your plan supports them.
4. Mint service keys per service per environment, store them in your secret manager, and confirm no personal token appears in any deployed configuration.
5. Set up tracing projects with your naming convention and wire in your applications, verifying that traces land in the intended workspace and project for each environment.
6. Establish the prompt promotion rule, pin production to specific prompt versions, and communicate that saving a prompt draft never changes production.
7. Stand up your first shared dataset and annotation queue so the collaborative muscles start developing early, and give annotators the narrow role they need.
8. Put a quarterly reminder on the calendar to review members, roles, and keys. Access reviews are boring precisely when they are working.

A team of three can complete this in an afternoon, and the structure it creates will still be serving you when the team is thirty. The recurring theme in healthy langsmith team workflows is that structure is cheap to create early and expensive to retrofit late. Workspaces, roles, and key discipline are the kind of infrastructure nobody celebrates and everybody depends on.

Access control will never be the exciting part of building LLM applications, but it is the part that determines whether your observability platform remains trustworthy as your team grows. Set the boundaries once, write them down, and let the structure do the enforcement so your engineers can spend their attention on traces, evals, and prompts rather than on wondering who changed what.

If you want to go deeper on everything LangSmith, from tracing fundamentals and evaluation pipelines to the team workflows covered here, the LangSmith Tutorial course on teachyou.ai walks through the entire platform hands-on, with real projects, production-grade setups, and the operational practices that separate demos from dependable LLM systems.