LangSmith Security Guide: API Keys, Traces, Data

An LLM tracing platform quietly becomes one of the most sensitive data stores in an organisation, because every prompt, retrieved document, tool call and model answer lands in it, and the keys that write to it are often long-lived and shared. LangSmith, the observability, evaluation and prompt engineering platform from LangChain, is used both as a SaaS service and as a self-hosted Kubernetes deployment. This guide covers its organisation and workspace model, roles, the three API key types, trace data handling, retention and deletion, audit logging and the settings that matter when you run it yourself. It is written for platform engineers, AI engineering leads and security teams who own LangSmith or are about to approve it. For the wider discipline of tracing LLM applications, see the LLM Observability Guide.

Key takeaways

Use the right key for the job. Applications that only send traces should use a tracing key (lsv2_tr_), automation should use a service key (lsv2_sk_), and personal access tokens (lsv2_pt_) should stay with humans.
Set an expiry on every key. LangSmith keys never expire by default, so an expiry date, an owner and a rotation date are your job.
Treat traces as regulated data. Inputs and outputs can contain personal data, secrets and confidential documents, so redact before data leaves the application with the SDK hide and anonymizer options.
Use workspaces as trust boundaries. Separate production from development and sensitive use cases from general ones, and grant Workspace Viewer or Editor rather than Admin.
Know your retention and your audit trail. Base traces live 14 days and extended traces up to 180 days on SaaS; Enterprise audit logs in OCSF format record who changed credentials and settings.

How identity and access work in LangSmith

LangSmith has a two-level hierarchy. The documentation describes the workspace (formerly called a tenant) as the object that "separates trust boundaries for resources and access control". Most hardening decisions are about one of the objects below.

Object	What it is	Security relevance
Organisation	Top-level container for users, SSO, OAuth provider configuration, custom roles, billing and usage	Organisation Admins have Admin rights in every workspace and can manage every member's personal access tokens.
Workspace	Container for tracing projects, datasets, prompts, evaluators and annotation queues	The trust boundary. Permissions are granted per workspace, and retention can be set per workspace on Enterprise.
Tracing project	A collection of traces from one application or environment	Holds the sensitive content. Its project ID is the `session_id` used for deletion.
Personal access token	A key tied to one user, prefix `lsv2_pt_`	Carries the user's own permissions and stops working when the user leaves the organisation.
Service key	An organisation-owned key for service accounts, prefix `lsv2_sk_`	Scoped to one workspace, several workspaces or the whole organisation. Can be deleted but not deactivated.
Tracing key	An organisation-owned write-only key, prefix `lsv2_tr_`	Can only submit traces and create projects. Cannot read stored traces or administer anything, and survives its creator leaving.

Human sign-in depends on the deployment. LangSmith Cloud offers email and password, GitHub and Google sign-in, with SAML SSO and SCIM provisioning on Enterprise plans. Self-hosted LangSmith supports OAuth 2.0 and OIDC SSO (the documented production option), basic authentication (email and password, aimed at trials) and a "none" mode intended only to verify an installation. The old ls__ key format stopped working on 22 October 2024, so any remaining reference to it marks an unmaintained integration.

Admin roles and privileged access

LangSmith separates organisation roles from workspace roles. Granular workspace RBAC is an Enterprise feature; on other plans every workspace member is effectively an Admin, which matters when you decide what data a small team should put in a shared workspace.

Role	Level	What it allows	Hardening note
Organisation Admin	Organisation	Full control of configuration, users, billing and workspaces; Admin in every workspace; manage all PATs	Keep to two or three named people with phishing-resistant MFA at the identity provider.
Organisation User	Organisation	Read-only at organisation level; can create PATs; workspace access granted per workspace	The default for engineers. Plus and Enterprise only; Developer plans make every user an Admin.
Organisation Viewer	Organisation	As Organisation User but cannot create PATs	Self-hosted only (Helm chart 0.11.25 or later). Useful for reviewers and auditors.
Organisation Operator	Organisation	Holds `organization:manage`, which grants access to audit logs	Give to the security team for audit log collection rather than full Admin.
Workspace Admin	Workspace	Full access including members, roles and service keys	One or two per workspace.
Workspace Editor	Workspace	Everything except workspace management (members, roles, service keys)	Normal role for engineers building and evaluating.
Workspace Viewer	Workspace	Read-only access to all workspace resources	Still reads every trace, so a production Viewer can read customer conversations. Size membership by data sensitivity.

Custom roles: Organisation Admins can define custom roles on Enterprise. Use them to give reviewers and annotators only the permissions their task needs instead of the built-in Editor role.
Joiners and leavers: on Enterprise Cloud use SCIM so that deprovisioning in the identity provider removes LangSmith access. Removing a user disables their PATs, but service keys and tracing keys they created keep working, which is correct for production and dangerous if nobody owns them. See the NHI Offboarding and Decommissioning Guide.

Integrations, API tokens and service accounts

Every LangSmith key is a non-human credential with direct access to sensitive data or to the means of creating it. Choosing the key type is the single most effective control you have.

Use case	Key type	Why
Production application or agent sending traces	Tracing key, scoped to one workspace	Write-only. A leaked key lets an attacker add noise or cost, not read your traces.
Evaluation pipeline, CI job or agent that reads datasets or prompts	Service key, scoped to the single workspace it needs	Organisation-owned, survives staff changes, can be scoped and given an expiry.
Administrative automation (user, workspace, key management)	Organisation-scoped service key with Organisation Admin permission	Highest-risk credential in the deployment. Store in a secrets manager, restrict who can retrieve it, monitor its use in audit logs.
A developer exploring the API or SDK locally	Personal access token with an expiry	Tied to the person and removed with them. The documentation advises against PATs for application authentication.

Expiry: keys never expire by default. Set an expiry when you create a key; an expired key cannot be reactivated or extended, so plan rotation before the date. Changes to a key take about a minute to apply because authentication results are cached.
Disable PAT creation where it is not needed: the organisation setting pat_creation_disabled (API only, also available self-hosted from Helm chart 0.11.25) stops new personal tokens being minted, which pushes teams towards owned service keys.
Storage: the SDKs read the key from LANGSMITH_API_KEY. Inject it at runtime from a secrets manager rather than committing .env files. The xAI API key leak shows how long a key committed in an .env file can stay valid when an alert reaches one developer instead of a security queue. See the API Key Management Guide and the Git Secret Scanning Guide.
Model provider keys inside LangSmith: the Playground forwards requests to model providers, so provider keys used there are exposed to anyone who can run or share prompts, and the Prompt Hub lets users publish and pull prompts and agents. In the AgentSmith issue reported by Noma Security (CVSS 8.8, disclosed 29 October 2024 and fixed 6 November 2024), a public agent configured with an attacker-controlled proxy provider could route a user's traffic, including their OpenAI key, through the attacker's server. Treat public prompts and agents as untrusted code, check the model endpoint before running them and use provider keys with spending limits. See the LLMjacking Guide.

Controlling what goes into a trace

The strongest control on trace sensitivity is to stop data leaving the application. The SDKs provide several layers, applied in this order of precedence: function-level processing, then the anonymizer, then client-level hiding.

Mechanism	Scope	Use it for
`LANGSMITH_HIDE_INPUTS=true`, `LANGSMITH_HIDE_OUTPUTS=true`, `LANGSMITH_HIDE_METADATA=true`	Whole process	Applications where content must never leave, keeping only timing, token and error data.
`hide_inputs`, `hide_outputs`, `hide_metadata` on the client (functions or booleans)	Client	Dropping or transforming specific fields such as uploaded documents.
`create_anonymizer` (Python) or `createAnonymizer` (TypeScript) with regex rules or a function	Client	Masking emails, card numbers, phone numbers and API keys. Processes 10 nesting levels by default (`max_depth`).
Presidio or Amazon Comprehend inside the anonymizer	Client	Entity-based PII detection where regex is not enough, at extra latency and cost.
`process_inputs`, `process_outputs` on `@traceable` (Python SDK 0.1.98+)	One function	Redacting a single tool call or retriever that handles sensitive records.
Conditional tracing	Per request	Turning tracing off for requests from regulated users or tenants.

The anonymizer serialises payloads to JSON, so complex regexes on large payloads add latency. Test redaction against real samples, including tool arguments and retrieved chunks, because secrets most often leak through tool calls rather than the user prompt. See the OWASP LLM Top 10 LLM02 Sensitive Information Disclosure Guide.

Sharing, retention and deletion

Public sharing: traces, datasets and prompts can be shared by public link. Use disable_public_sharing on every workspace that holds real data and unshare_all to withdraw existing links.
Retention: base traces are kept 14 days and extended traces up to 180 days on SaaS (30, 60, 90, 120, 150 or 180 days, configurable per project or per workspace on Enterprise). Traces are upgraded to extended retention automatically by API feedback sent with extend_trace_retention=true, online evaluators and automation rules, so a broad automation rule can silently lengthen retention of sensitive traces.
Deletion: delete traces with POST /api/v1/runs/delete using trace_ids and the project's session_id (up to 1,000 per request), or by metadata key and value. Deletions run as a weekend batch job with no confirmation, so verify by querying again. Dataset examples need hard_delete to remove data from all dataset versions. Tag traces with a user or tenant identifier in metadata so you can answer erasure requests.

Logging and detection

LangSmith Enterprise audit logs record administrative and configuration changes, including changes to organisation settings, membership, credentials and workspaces. They are retrieved with GET /api/v1/audit-logs in OCSF v1.7.0 API Activity format (class 6003), retained for up to 400 days, and readable by Organisation Admins and Organisation Operators. Self-hosted deployments need Helm chart 0.12.33 or later and the DEFAULT_ORG_FEATURE_CAN_USE_AUDIT_LOGS setting. Pull them into your SIEM on a schedule rather than relying on the retention window.

Signal	Where to find it	Why it matters
Key created, role changed or key deleted	Audit log `api.operation` such as `create_api_key`	New organisation-scoped service keys are the highest-value persistence path.
Change made with a key rather than a session	`actor.user.credential_uid` is not null	Automation changing members or settings should match a known pipeline.
Failed administrative operations	`status` is `Failure`	Repeated failures from one credential suggest probing.
Public sharing enabled or new share links	Audit log and workspace sharing settings	Shared links expose traces outside the organisation.
Trace volume spikes or HTTP 429 responses for a key	Usage dashboards and application logs	A leaked tracing key or runaway agent shows up as volume first.
Self-hosted: frontend and API access logs	Ingress or load balancer logs for the `langsmith-frontend` service	Only the frontend should be reachable; anything else exposed is a finding.

Useful measures that show the controls are working:

Percentage of active keys with an expiry date and a named owner (target 100%).
Number of personal access tokens used by non-interactive workloads (target zero).
Number of organisation-scoped service keys (target as low as possible, each justified).
Percentage of production tracing projects with redaction tests in CI.
Workspaces holding production data with public sharing disabled (target 100%).
Median time from a staff departure to removal of their LangSmith access.

Hardening baseline

Cloud or self-hosted

Factor	LangSmith Cloud	Self-hosted LangSmith
Where traces live	Vendor infrastructure	Your ClickHouse, PostgreSQL, Redis and blob storage
Retention ceiling	180 days for extended traces	Not subject to the 180-day cap; you set TTLs and blob lifecycle rules
Identity	SAML SSO and SCIM on Enterprise	OIDC SSO, basic auth for trials
Operational burden	Low	Kubernetes, data stores, patching, backups, encryption and network policy are yours
Fits best	Teams that can redact before sending and accept vendor processing	Data residency or contractual limits that rule out third-party processing of prompts

Self-hosting is an Enterprise add-on: it does not make traces less sensitive, it changes who must protect them.

Self-hosted settings that matter

Authentication: use authType: mixed with oauth.enabled: true and the OIDC client secret flow (oauthClientId, oauthClientSecret, oauthIssuerUrl). The PKCE flow without a client secret was deprecated in v16 and removed in v17. Never run production in "none" mode, which cannot be upgraded to OAuth later. Sessions default to one day through OAUTH_SESSION_MAX_SEC (maximum 604800 seconds); set OAUTH_IDP_LOGOUT_ENABLED=true so logout ends the IdP session too.
Basic auth, if used: the initial admin password must be at least 12 characters with lower case, upper case and a symbol, and basicAuth.jwtSecret should be a random string of at least 32 characters. Changing it logs out every user.
Secrets: config.apiKeySalt hashes API keys at rest. Set it once and protect it: changing it invalidates every existing key. Supply it, the licence key, JWT secret, the Ed25519 signingJwks and the Insights and Chat Fernet encryption keys through config.existingSecretName from your secrets manager rather than plain Helm values. See the Kubernetes Secrets Security Guide.
Network: only the frontend needs to be exposed to users. Terminate TLS in front of it, keep ClickHouse, PostgreSQL and Redis on private networks with authentication, and restrict egress to beacon.langchain.com (licence verification and usage reporting, not needed in offline mode) and the model providers the Playground, Insights and Chat use.
Code execution: the ACE backend runs custom evaluator code. Keep it isolated with network policies and no access to cloud metadata endpoints. See the AI Agent Sandboxing and Code Execution Guide.
Data at rest: enable encryption on the managed databases and blob storage and add a lifecycle rule for each custom retention prefix (for example ttl_90d/), or blobs outlive the trace records.

Rollout order

Inventory: list organisations, workspaces, members, and every key with its type, scope, creator and last use. Retire any remaining ls__ references.
Redact first: before onboarding a production application, add anonymizer rules and test them in a non-production workspace against realistic traces, including tool outputs.
Restructure workspaces: split production from development and give production the smallest membership. On Enterprise, apply Workspace Viewer and Editor roles.
Replace keys: issue tracing keys for production apps and scoped service keys for pipelines, each with an expiry, then delete the old PATs and keys.
Lock settings: disable public sharing, set retention per workspace, turn on pat_creation_disabled if your workflow allows.
Monitor: stream audit logs to the SIEM and alert on key creation, organisation-scoped keys and sharing changes.

Common misconfigurations

A developer's PAT in production: the application breaks when the developer leaves, or worse, the PAT carries Admin rights across workspaces. Use tracing or service keys.
Keys without expiry or owner: the default behaviour, not an edge case.
Raw prompts and tool outputs traced: secrets pasted by users, retrieved HR documents and tool responses containing tokens all land in traces and then in datasets built from them.
Automation rules extending retention: an evaluator or rule on a production project quietly moves sensitive traces from 14 to up to 180 days.
Public share links left open: a link shared during debugging stays valid long after the incident is closed.
Self-hosted with bundled data stores and default exposure: in-cluster ClickHouse, PostgreSQL and Redis are fine for a trial, but production needs external, encrypted, backed-up services and network policy. Exposed AI tooling with secrets in its environment is a proven target, as the Langflow CVE-2025-3248 exploitation showed for a related AI workflow tool.

Framework mapping

Control area	NIST SP 800-53 Rev 5	NIST CSF 2.0	ISO/IEC 27001:2022 Annex A	ATT&CK threat addressed
Roles, workspaces, joiners and leavers	AC-2, AC-6	PR.AA-05	A.5.15, A.5.18	T1078.004 Cloud Accounts
Key types, expiry and storage	IA-5	PR.AA-05	A.5.17, A.8.5	T1552.001 Credentials In Files, T1528 Steal Application Access Token
Trace redaction and retention	SC-28	PR.DS-01, ID.AM-07	A.8.11, A.8.12	T1552 Unsecured Credentials
Audit logs and monitoring	AU-2, AU-6	DE.CM-09	A.8.15, A.8.16	All of the above
Self-hosted configuration and exposure	CM-6, CM-7, SC-7, SC-8	PR.PS-01	A.8.9, A.8.20	T1190 Exploit Public-Facing Application

The data handling rows also map to OWASP Top 10 for LLM Applications 2025 LLM02 Sensitive Information Disclosure. See the OWASP Top 10 for LLM Applications Guide.

Practitioner checklist

Inventory every LangSmith key with type, scope, owner, expiry and last use; delete any without an owner.
Move production tracing to workspace-scoped tracing keys (lsv2_tr_) and pipelines to scoped service keys (lsv2_sk_).
Set an expiry on every key and a rotation reminder ahead of it.
Keep keys in a secrets manager and scan repositories for lsv2_ prefixes.
Implement and test anonymizer or hide rules for every production application, including tool inputs and outputs.
Separate production and development workspaces and restrict production membership, including Viewers.
Disable public sharing on workspaces with real data and review retention and automation rules per project.
Connect SSO (and SCIM on Enterprise Cloud) and keep Organisation Admins to a small named group.
Collect audit logs into the SIEM and alert on key creation, role changes and sharing changes.
Self-hosted: OIDC with client secret, secrets via existingSecretName, protected apiKeySalt, only the frontend exposed, restricted egress.

LangSmith Security Guide: API Keys, Traces and Sensitive Data