, // populated for validated-token auth
};
```
Annotate the injected `runtime` parameter as `ManagedDeepAgentRuntime` so you get typed access to `identity` (and optional `credentials`). Use it whenever a tool or middleware hook needs to know *who* triggered the run, for personalization, audit logs, or branching on verified claims, without trusting anything from the request body.
```python tools/whoami.py theme={null}
from langchain.tools import tool
from managed_deepagents import ManagedDeepAgentRuntime
@tool
def whoami(runtime: ManagedDeepAgentRuntime) -> str:
"""Return the authenticated user id for this run."""
identity = runtime.identity
if not identity:
return "No authenticated caller on this run."
return f"Signed in as {identity['user']['id']}"
```
```ts tools/whoami.ts theme={null}
import { z } from "zod";
import { tool } from "langchain";
import type { ManagedDeepAgentRuntime } from "managed-deepagents";
export const whoami = tool(
async (_input, runtime: ManagedDeepAgentRuntime) => {
const identity = runtime.identity;
if (!identity) {
return "No authenticated caller on this run.";
}
return `Signed in as ${identity.user.id}`;
},
{
name: "whoami",
description: "Return the authenticated user id for this run.",
schema: z.object({}),
},
);
```
The same type works in middleware hooks:
```python middleware/audit.py theme={null}
from langchain.agents.middleware import AgentState, before_model
from managed_deepagents import ManagedDeepAgentRuntime
def audit_middleware():
@before_model
def audit(state: AgentState, runtime: ManagedDeepAgentRuntime) -> dict | None:
user = runtime.identity["user"]["id"] if runtime.identity else "anonymous"
print(f"[audit] {user} model call with {len(state['messages'])} messages")
return None
return audit
```
```ts middleware/audit.ts theme={null}
import { createMiddleware } from "langchain";
import type { ManagedDeepAgentRuntime } from "managed-deepagents";
export function auditMiddleware() {
return createMiddleware({
name: "audit",
beforeModel: (state, runtime: ManagedDeepAgentRuntime) => {
const user = runtime.identity?.user.id ?? "anonymous";
console.log(
`[audit] ${user} model call with ${state.messages.length} messages`
);
return undefined;
},
});
}
```
Prefer `runtime.identity` over client-supplied configurable keys for user or organization ids. For other per-run values such as feature flags, use normal LangChain runtime context.
## Customize scoping
The common shapes cover most cases. To customize, set `scope` per axis:
| Axis | Values | Meaning |
| ------------- | --------------------------------------- | ------------------------------------------------------- |
| `threads` | `user`, `conversation`, `organization` | Who can open or resume the conversation |
| `memory` | `user`, `organization`, `agent`, `none` | Which Context Hub memory slice is remounted for the run |
| `credentials` | `user`, `agent`, `none`, `custom` | Whose credentials downstream calls use |
Do not set any scoping axis to `"organization"` when organizations are optional, there may be no organization to scope by. If a request is missing the user or organization id that scoping needs, Managed Deep Agents rejects it with 403 instead of falling back to shared data.
For how memory paths remount under each scope, see [Scope memory with identity](/langsmith/managed-deep-agents-memory#scope-memory-with-identity).
### Downstream credentials
Declare `credentials` when downstream calls need more than an agent-wide token. `credentials` accepts one resolver or a map keyed by target name, so one deployment can integrate several platforms. Providing any resolver puts the credentials axis into `custom` mode; tools then call `runtime.credentials.for(target)` to obtain the headers for that request. Resolved credentials are kept in memory and are never written to thread state or traces.
The token that proves a caller's identity is not automatically a credential for downstream APIs. For example, a Supabase access token lets Managed Deep Agents identify the caller, but it is not a GitHub API token. Your backend or credential service must hold (and, when needed, refresh) the caller's separately authorized GitHub credential.
For GitHub, the first-party `credentials.github` resolver chains token sources per intent. When the chain reads `"user"` tokens, Connect-with-GitHub OAuth routes mount automatically—there is nothing else to declare:
```python identity.py theme={null}
import os
from managed_deepagents import auth, credentials, define_identity
identity = define_identity(
auth=auth.supabase(project_ref="your-project-ref"),
credentials={
"github": credentials.github(
read=["user", "pat"],
write=["user"],
pat=os.environ.get("GITHUB_TOKEN") or os.environ.get("GITHUB_PAT"),
),
},
)
```
```ts identity.ts theme={null}
import { auth, credentials, defineIdentity } from "managed-deepagents";
export const identity = defineIdentity({
auth: auth.supabase({ projectRef: "your-project-ref" }),
credentials: {
github: credentials.github({
read: ["user", "pat"],
write: ["user"],
pat: process.env.GITHUB_TOKEN ?? process.env.GITHUB_PAT,
}),
},
});
```
In a GitHub tool, request the headers with `await runtime.credentials.for({ kind: "connection", name: "github", intent: "write" })` and pass them to your GitHub client.
For other platforms, supply a `resolve` function yourself. The following shape lets a user open pull requests as themselves after your application has stored their GitHub grant. `getGitHubAccessToken` is application code: it looks up and refreshes that grant in your server-side credential store.
```ts identity.ts theme={null}
import { auth, defineIdentity } from "managed-deepagents";
import { getGitHubAccessToken } from "./github-credentials.js";
export const identity = defineIdentity({
auth: auth.supabase({ projectRef: "your-project-ref" }),
credentials: {
github: {
async resolve({ identity, target }) {
const credential = await getGitHubAccessToken(identity.user.id);
if (!credential) {
throw new Error("Connect GitHub before using GitHub tools.");
}
return {
headers: { Authorization: `Bearer ${credential.token}` },
expiresAt: credential.expiresAt.toISOString(),
};
},
},
},
});
```
To expose LangSmith capabilities to browsers or other untrusted callers, add a [LangSmith connector](/langsmith/managed-deep-agents-connectors/langsmith). It requires identity so capability routes can resolve the caller and prove ownership before calling LangSmith server-side.
### Connect-with-X routes
Connect-with-X binds an MDA user to an external account via OAuth—either to link a channel identity (Slack) or to populate a per-user credential vault (GitHub). Routes are **inferred** from the rest of the declaration on user-scoped deployments:
* Connect-with-GitHub mounts when a credential chain reads `"user"` tokens.
* Connect-with-Slack mounts when a [Slack channel](/langsmith/managed-deep-agents-channels/slack) is declared.
Declare `connect` only to add providers the inference cannot see, such as a custom OAuth provider:
```python identity.py theme={null}
from managed_deepagents import connect, define_identity
identity = define_identity(
connect=[connect.github(), connect.slack()],
)
```
```ts identity.ts theme={null}
import { connect, defineIdentity } from "managed-deepagents";
export const identity = defineIdentity({
connect: [connect.github(), connect.slack()],
});
```
## Provider setup guides
The `auth` namespace ships providers for the common identity providers:
| Provider | Factory | Verification |
| --------------- | -------------------------------------- | ------------------------------ |
| Auth0 | `auth.auth0({ domain, audience? })` | JWKS |
| Clerk | `auth.clerk({ domain })` | JWKS |
| Okta | `auth.okta({ domain, audience? })` | JWKS |
| Amazon Cognito | `auth.cognito({ userPoolId, region })` | JWKS |
| Microsoft Entra | `auth.entra({ tenantId, audience? })` | JWKS |
| Google | `auth.google({ audience? })` | JWKS |
| Supabase | `auth.supabase(...)` | JWKS (or legacy introspection) |
| Any OIDC IdP | `auth.oidc({ issuer, audience? })` | OIDC discovery |
| GitHub | `auth.github()` | Opaque token introspection |
| Guest | `auth.guest(...)` | MDA-signed tokens |
Each factory returns a plain provider object, so spread it to override the claim mapping (`user`, `organization`, `groups`, `email`) when the token's claims do not match the defaults. The tabs below cover the providers that need extra setup. Use one provider, or combine them as in the [validated token example](#validated-token-browser-direct).
Anonymous visitors get a short-lived, user-scoped session without signing in. Managed Deep Agents signs guest tokens with `MDA_GUEST_SIGNING_KEY` (HS256) and maps `sub` → user.
| Option | Required | Description |
| ---------------------------- | -------- | ------------------------------------------------------ |
| `ttl` | No | Token lifetime (for example `"24h"`) |
| `userPrefix` / `user_prefix` | No | Prefix for generated user ids (for example `"guest:"`) |
Guest is usually combined with another IdP, as in the [validated token example](#validated-token-browser-direct).
Set `MDA_GUEST_SIGNING_KEY` in `.env` for `mda dev` and as a hosted deployment secret for `mda deploy`.
#### Claim a guest token
With guest issuance enabled, the deployment exposes `POST /identity/guest`. Send an empty `POST` with `Content-Type: application/json`. If the deployment requires a public app key (`LANGGRAPH_AUTH_SECRET`), also send `X-Auth-Key`.
```bash theme={null}
curl -X POST "$LANGGRAPH_API_URL/identity/guest" \
-H "Content-Type: application/json"
```
On success:
```json theme={null}
{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```
#### Use the guest token
Send the token the same way you send IdP access tokens:
```http theme={null}
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```
```typescript theme={null}
import { Client } from "@langchain/langgraph-sdk";
const response = await fetch(`${deploymentUrl}/identity/guest`, {
method: "POST",
headers: { "Content-Type": "application/json" },
});
const { token } = (await response.json()) as { token: string };
const client = new Client({
apiUrl: deploymentUrl,
defaultHeaders: { Authorization: `Bearer ${token}` },
});
```
```python theme={null}
import httpx
from langgraph_sdk import get_client
response = httpx.post(f"{deployment_url}/identity/guest")
response.raise_for_status()
token = response.json()["token"]
client = get_client(
url=deployment_url,
headers={"Authorization": f"Bearer {token}"},
)
```
For browser apps, proxy guest issuance through your own backend and store the token in an `httpOnly` cookie. That keeps the same guest user across reloads until `exp` and lets you handle rate limits before calling the deployment.
Reclaim a token when the current one is expired or missing. While a token is still valid, reuse it so the guest keeps the same user id, threads, and memory scope for the token lifetime.
JWKS by default (asymmetric JWTs). Maps `sub` → user. Pass only one of `projectRef` or `url`.
| Option | Required | Description |
| ---------------------------- | ---------------------------- | ---------------------------------------------------------- |
| `projectRef` / `project_ref` | One of `projectRef` or `url` | Subdomain before `.supabase.co` |
| `url` | One of `projectRef` or `url` | Project URL or custom auth domain |
| `introspect` | No | `true` for legacy HS256 projects that need `/auth/v1/user` |
Use `auth.supabase(...)` alone, or combine it with guest as in the [validated token example](#validated-token-browser-direct).
After sign-in, send `session.access_token` from [@supabase/supabase-js](https://supabase.com/docs/reference/javascript/auth-getsession). See also [Supabase Auth](https://supabase.com/docs/guides/auth) and [JWT signing keys](https://supabase.com/docs/guides/auth/signing-keys).
For legacy introspection, use `introspect: true` and set `SUPABASE_ANON_KEY` on the deployment.
Opaque token introspection via `GET https://api.github.com/user`. Maps `login` → user, `email` → email. `auth.github()` takes no options.
```python identity.py theme={null}
from managed_deepagents import auth, define_identity
identity = define_identity(auth=auth.github())
```
```ts identity.ts theme={null}
import { auth, defineIdentity } from "managed-deepagents";
export const identity = defineIdentity({ auth: auth.github() });
```
Complete a [GitHub OAuth App](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps) sign-in flow, then send the **user access token**. Do not send OAuth client secrets to the deployment. See also [Authorizing OAuth apps](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps) and [Get the authenticated user](https://docs.github.com/en/rest/users/users#get-the-authenticated-user).
For production, prefer [backend](#backend-recommended-default) auth: keep the GitHub token on your API, and proxy with `X-MDA-Ingress-Secret` + `X-MDA-User-Id` (for example the GitHub `login`).
## Test and deploy
Test the project locally with [`mda dev`](/langsmith/managed-deep-agents-cli#develop-locally), then deploy it with [`mda deploy`](/langsmith/managed-deep-agents-deploy). Open deployment traces in LangSmith to inspect model calls, tool calls, errors, and latency.
Identity misconfiguration usually surfaces as 401 (auth) or 403 (store/thread scope) during local Studio or the first authenticated request. Confirm the matching secret is present and that backend proxies attach the reserved headers.
## Next steps
See how identity remounts per-user or per-organization memory.
Read `runtime.identity` from authored tools.
Supply `identity.json` fixtures for Harbor tasks when identity is declared.
Run cron agents, including the `agent` scope shape.
Expose constrained LangSmith capabilities to untrusted callers.
Receive Slack Events with a shared bot or Connect-with-Slack linking.
See how compile and deploy wire auth into the runtime.
Look up project files and identity wiring in `mda`.
***
[Connect these docs](/use-these-docs) to Claude, VSCode, and more via MCP for real-time answers.
[Edit this page on GitHub](https://github.com/langchain-ai/docs/edit/main/src/langsmith/managed-deep-agents-identity.mdx) or [file an issue](https://github.com/langchain-ai/docs/issues/new/choose).