LangChain and LangGraph applications hold every credential their agents use, and when deployed on the LangGraph Agent Server or traced to LangSmith they add their own API keys, workspaces and authorisation layer that teams often leave at defaults. LangChain's own security policy tells developers to assume any credential an LLM application holds may be used in any way its permissions allow. This guide turns that into concrete controls for the LangChain stack: the credentials inside the application, Agent Server authentication and resource authorisation, LangSmith organisation roles and key types, trace data exposure, and the serialisation flaws that have turned stored data into secret disclosure. The cross-framework view (CrewAI, AutoGen and others, code execution settings, multi-agent delegation) is in the Securing Agent Frameworks Guide and is not repeated here. It is written for application security engineers, platform teams and developers running LangChain or LangGraph in production. Details are from LangChain documentation and GitHub advisories checked 27 October 2026.
This is an independent guide from NHI Mgmt Group, based on LangChain's public documentation as of November 2026. It is not sponsored or reviewed by LangChain. Product features change, so confirm settings against LangChain's current documentation.
Key takeaways
- The framework has no identity of its own. A LangChain agent acts with whatever API keys, database credentials and OAuth tokens the application process holds, so scoping those credentials is the primary control.
- Self-hosted Agent Server has no default authentication. On LangSmith deployments the default is a LangSmith API key in
x-api-key; self-hosted servers are open until you implement@auth.authenticate. - Authorisation is yours to write. Without
@auth.onhandlers that tag resources with an owner and return filters, any authenticated caller can read every thread, assistant, cron and store item. - Use service keys, not personal tokens. LangSmith Personal Access Tokens (
lsv2_pt_) carry a user's permissions and die when the user leaves; service keys (lsv2_sk_) and tracing keys (lsv2_tr_) are built for applications, and no key expires unless you set an expiry. - Serialised data can carry secrets out. Keep
langchain-coreon a current release (0.3.81 or 1.2.5 and later), keepsecrets_from_envoff and treat stored objects as untrusted input.
How identity and access work in LangChain and LangGraph
There are three identity planes in a typical deployment, and each has a different owner.
| Plane | Who authenticates | Mechanism | Default |
|---|---|---|---|
| Application to tools and models | The agent process to model providers, databases, SaaS APIs and MCP servers | Credentials loaded by the application: environment variables, secrets managers, OAuth tokens passed in run context | Whatever the developer configured, often broad shared keys |
| Client to Agent Server | End users or front-end applications calling a LangGraph deployment | LangSmith API key (x-api-key) on LangSmith deployments, or custom auth via the Auth object | LangSmith key on LangSmith; none when self-hosted |
| People and services to LangSmith | Developers, operators and tracing clients | Organisation and workspace roles; PATs, service keys, tracing keys; SSO at organisation level | Developer organisations make every user Organization Admin; RBAC is Enterprise-only |
- User-scoped credentials: values returned from
@auth.authenticateare added to the run context (available in the app asconfig["configuration"]["langgraph_auth_user"]), so an agent can call MCP servers, databases or other agents with the end user's credentials rather than a shared service credential. This is the pattern to prefer whenever the downstream system can enforce per-user access. - LangChain's three principles: limit permissions (read-only credentials, blocked sensitive resources, sandboxing such as containers, proxies), anticipate misuse (a credential that allows deletion should be treated as if it will be used to delete), and defence in depth (combine read-only permissions with sandboxing rather than relying on one safeguard).
For the credential side in depth, see the Credential Vaulting for AI Agents Guide.
Admin roles and privileged access
LangSmith organisation and workspace roles
| Role | Scope | Can do | Notes |
|---|---|---|---|
| Organization Admin | Organisation | Billing, workspaces, users, custom roles; Admin on every workspace | Default for every user in Developer organisations |
| Organization User | Organisation | Read-only at organisation level; can create PATs | Plus and Enterprise plans |
| Organization Viewer | Organisation | As Organization User but cannot create PATs | Self-hosted needs Helm chart 0.11.25 or later |
| Workspace Admin | Workspace | Full access, including users, roles and service keys | Treat as privileged |
| Workspace Editor | Workspace | Everything except workspace management | Typical developer role |
| Workspace Viewer | Workspace | Read-only | Reviewers, support |
- RBAC depends on plan: LangSmith documents workspace RBAC and custom workspace roles as Enterprise-only; on other plans all users get the Admin role. If you are not on a plan with RBAC, the only isolation is between workspaces, so put production tracing and deployments in a workspace with very few members.
- Workspaces are the trust boundary: LangSmith recommends one workspace per team. Separate production from development workspaces so that developers can experiment without reading production traces.
- Prefer Organization Viewer for people who should not mint tokens, because Organization User can create PATs that carry their permissions into scripts.
Agent Server operators
Whoever can deploy a graph or edit langgraph.json controls the authentication handler path, whether auth.allow_langsmith_api_keys is enabled alongside custom auth, and which environment variables (and therefore secrets) the server receives. Gate deployment through CI with review, and keep that configuration in version control.
Integrations, API tokens and service accounts
LangSmith key types
| Key | Prefix | Bound to | Use for | Lifecycle |
|---|---|---|---|---|
| Personal Access Token | lsv2_pt_ | A user and that user's permissions | Individual developer tooling only; not recommended for applications | Stops working when the user leaves; can be deactivated and reactivated |
| Service key | lsv2_sk_ | A service account, scoped to one, several or all workspaces | Applications, CI, deployments; target a workspace with X-Tenant-Id | Created by admins; can be deleted but not deactivated |
| Tracing key | lsv2_tr_ | The organisation, fixed permissions to submit traces and create projects | Applications that only send traces | Cannot read traces or administer; survives creator leaving |
| Legacy key | ls__ | - | None | No longer supported |
- Least privilege for tracing: an application that only emits traces should hold a tracing key, which cannot read stored traces. A leaked service key with all-workspace scope exposes every trace and prompt in the organisation.
- Set expiry: expiration dates are optional and keys never expire by default. Set one on every key and rotate before it lapses; expired keys cannot be reactivated.
- Storage: keep
LANGSMITH_API_KEYand model provider keys in a secrets manager injected at runtime, not in notebooks,.envfiles committed to repositories or container images. See the LLMjacking Guide.
Agent Server authentication and authorisation
- Authenticate every request: implement
@auth.authenticateto validate a bearer token from your IdP (signature, issuer, audience, expiry) and return a user dict withidentityand, where useful,permissions,roleororg_id. RaiseAuth.exceptions.HTTPExceptionwith 401 on failure. - Authorise by resource: add
@auth.onhandlers. The single-owner pattern setsvalue["metadata"]["owner"]on create and returns{"owner": ctx.user.identity}as a filter on read and search. The most specific handler wins: global@auth.on, then resource (@auth.on.threads,.assistants,.crons), then action (@auth.on.threads.create_run). - Scope the store: store handlers work differently: they rewrite the
namespaceinvalueto scope long-term memory per user rather than returning filters. Without this, one user's stored memories are readable by others. - Check permissions for writes: use the permission pattern (for example
threads:write) for actions such ascreate_run, because runs inherit access from their parent thread. - Decide on LangSmith keys: enabling
auth.allow_langsmith_api_keyslets API keys work alongside custom auth. Anyone holding a workspace key then bypasses your user model, so enable it only for operator access and log it.
Tools, MCP and model providers
- Per-tool credentials: give each tool its own credential with the narrowest scope: read-only database users limited to required tables (as LangChain's policy suggests), API keys restricted to endpoints, file access limited to one directory.
- MCP: the newer
langchain.mcpMCPAdapter(beta,langchain[mcp]1.4.0 or later) connects over Streamable HTTP for URLs or launches a subprocess over stdio for a script path; it rejects strings that are not URL-shaped, because a string naming an existing script would otherwise launch as a subprocess. Treat stdio server definitions as code execution and remote servers as third parties. See the MCP Security Guide. - Delegated calls: pass end-user tokens from
langgraph_auth_userto downstream services that enforce per-user access, rather than one service credential that sees everything. See the OAuth Token Exchange and Delegation Guide.
Serialisation and the secrets it can leak
LangChain persists objects through dumps(), dumpd(), load() and loads(), and LangGraph persists checkpoints. LangChain publishes security fixes under its security policy; apply security updates promptly, and treat any stored framework object as untrusted input unless only your code could have written it.
| Area | Package and versions | Effect | Fix and hardening |
|---|---|---|---|
| Object serialisation | langchain-core < 0.3.81 and >= 1.0.0, < 1.2.5 | Serialised dictionaries with 'lc' keys can be revived as LangChain objects on load(), so secrets_from_env=True could expose environment variables | Upgrade to 0.3.81 or 1.2.5; keep secrets_from_env=False; set allowed_objects to an explicit list; leave init_validator at its default, which blocks Jinja2 templates; review astream_events(version="v1") and Runnable.astream_log() |
| Checkpoint serialisation (see the Securing Agent Frameworks Guide) | LangGraph checkpoint packages before 3.0.0 | Code execution when deserialising checkpoint payloads in the JSON fallback mode | Upgrade; protect the checkpointer database with its own credentials, encryption and network limits |
- Where user data hides: fields such as
additional_kwargs,response_metadataand metadata can carry user-controlled content into serialised output. Model output counts as user-controlled when the model has read untrusted content. - Identity angle: deserialisation issues can reach only the secrets present in the process environment. Workload identity and short-lived tokens shrink what any such flaw can reach. See the Insecure Deserialisation Guide.
Logging and detection
- Traces are sensitive data: LangSmith traces contain prompts, retrieved documents, tool inputs and outputs. Masking runs client-side before data leaves the application:
LANGSMITH_HIDE_INPUTS=true,LANGSMITH_HIDE_OUTPUTS=trueandLANGSMITH_HIDE_METADATA=truehide everything;hide_inputsandhide_outputsfunctions, an anonymizer fromcreate_anonymizer, orprocess_inputson@traceableredact selectively. Use conditional tracing for requests that must never be traced. - Retention: base trace retention is 14 days; LangSmith states that from 14 September 2026 the maximum extended retention for SaaS is 180 days. Deletion by trace ID or metadata runs on weekends without confirmation, so re-query to verify.
- Server-side logs: log every
@auth.authenticatefailure and every 403 from@auth.onhandlers with identity and resource; these are the signals for enumeration of other users' threads. - Credential use: watch model provider usage per key for spikes and new source networks, and cloud or database audit logs for the agent's credentials touching new resources.
| Signal | Source | Why it matters |
|---|---|---|
| Repeated 403s on threads or store for one identity | Agent Server auth handler logs | Attempts to read other users' state |
| LangSmith key used from an unknown network or after its owner left | LangSmith admin views, network logs | Leaked or orphaned key |
| Model provider spend jump for one key | Provider billing and usage APIs | Key theft or agent loop |
| Agent database user issuing writes or DDL | Database audit logs | Prompt-driven misuse of an over-scoped credential |
Unexpected load() of objects outside the allowed list | Application logs around deserialisation | Serialisation injection attempts |
Metrics: share of deployments with custom auth and owner filters on all resources; applications using PATs instead of service or tracing keys (target zero); keys without expiry; langchain-core and checkpoint package versions below the fixed releases; tools whose credentials are read-only; traces sent without masking where data classification requires it.
Hardening baseline
- Inventory: list every LangChain or LangGraph application, its deployment target (LangSmith, self-hosted Agent Server, embedded), the credentials it loads and the LangSmith keys it uses.
- Patch and pin: upgrade
langchain-coreto 0.3.81, 1.2.5 or later and LangGraph checkpoint packages to 3.0.0 or later; pin versions in a lock file and scan dependencies in CI. - Authenticate the server: implement
@auth.authenticateagainst your IdP on every self-hosted Agent Server before exposing it beyond localhost; on LangSmith deployments, replace shared API keys with custom auth for end-user traffic. - Authorise resources: add owner metadata and filters for threads, assistants and crons, and namespace scoping for the store. Test with two users who try to read each other's threads; both must get 403 or empty results.
- Re-key LangSmith: move applications from PATs to tracing keys (trace-only) or workspace-scoped service keys, set expiry on all keys, and remove legacy keys.
- Scope tool credentials: read-only, table- or endpoint-limited credentials per tool, from a secrets manager; containers or sandboxes for file and code tools.
- Mask and retain deliberately: configure hiding or anonymisation for traces that carry personal or secret data, and set retention to policy.
- Roll out safely: introduce new auth handlers behind a feature flag or on a staging deployment, replay recorded traffic, then switch; rollback is reverting the
langgraph.jsonauth path through the same reviewed pipeline.
Common misconfigurations
- Self-hosted server with no auth: a LangGraph server deployed for a demo is reachable on the network and lets anyone create runs that use the server's credentials.
- Authentication without authorisation: custom auth is in place but no
@auth.onhandlers, so every signed-in user can list and read every thread. - Developer PAT in production: the application traces with a personal token that has Admin rights and stops working, or keeps working, depending on what happens to the developer.
- One all-workspace service key everywhere: the same key sits in development laptops, CI and production, so a leak anywhere exposes production traces.
- Agent with an admin database user: the SQL tool connects with an owner account because "read-only broke a query", against LangChain's own advice to scope database credentials to the tables needed.
- Unmasked traces of regulated data: retrieved customer records and tool outputs are stored in LangSmith for months without anyone deciding that they should be.
- Old
langchain-corethrough a transitive dependency: the application pins a recent LangChain but another package pulls an unpatched core version.
Framework mapping
| Area | NIST SP 800-53 Rev. 5 | NIST CSF 2.0 | OWASP |
|---|---|---|---|
| Agent Server authentication and resource filters | IA-2, AC-3 Access Enforcement | PR.AA-05 | API1:2023 Broken Object Level Authorization |
| Tool credential scoping | AC-6 Least Privilege, IA-5 Authenticator Management | PR.AA-01 | LLM06 Excessive Agency |
| Serialisation flaws and patching | SI-2 Flaw Remediation | - | LLM03 Supply Chain |
| Trace masking and retention | AU-2 Event Logging, SI-12 Information Management and Retention | DE.CM-03 | LLM02 Sensitive Information Disclosure |
Practitioner checklist
- Upgrade
langchain-coreto 0.3.81 or 1.2.5 or later and LangGraph checkpoint packages to 3.0.0 or later, checking transitive versions. - Never
load()orloads()untrusted data; setallowed_objectsexplicitly and keepsecrets_from_envoff. - Implement
@auth.authenticateon every Agent Server, especially self-hosted ones. - Add owner metadata and filters with
@auth.onfor threads, assistants and crons, and namespace scoping for the store. - Replace PATs in applications with tracing keys or workspace-scoped service keys, all with expiry.
- Separate production and development LangSmith workspaces and keep Admin roles to a few people.
- Give each tool its own narrowly scoped credential from a secrets manager.
- Pass end-user credentials through run context where downstream systems enforce per-user access.
- Mask sensitive trace content client-side and set retention to policy.
Standards and references
- LangChain: Security policy
- LangChain: Authentication and access control for Agent Server
- LangChain: LangSmith administration overview
- LangChain: Mask inputs and outputs in traces
- LangChain: LangSmith data retention and compliance
- LangChain: MCP
- OWASP: Top 10 for LLM Applications 2025
Related NHI Mgmt Group resources: Securing Agent Frameworks Guide · Credential Vaulting for AI Agents Guide · MCP Security Guide · AI Agent Memory Security Guide