, // populated for validated_token ingress
};
```
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 actor id for this run."""
identity = runtime.identity
if not identity:
return "No authenticated caller on this run."
return f"Signed in as {identity['actor']['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.actor.id}`;
},
{
name: "whoami",
description: "Return the authenticated actor 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["actor"]["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?.actor.id ?? "anonymous";
console.log(
`[audit] ${user} model call with ${state.messages.length} messages`
);
return undefined;
},
});
}
```
Prefer `runtime.identity` over client-supplied configurable keys for actor or tenant ids. For other per-run values such as feature flags, use normal LangChain runtime context.
## Customize scoping
Presets cover the common cases. To customize, set `scoping` explicitly:
| Axis | Values | Meaning |
| ------------- | ---------------------------------- | ------------------------------------------------------- |
| `threads` | `actor`, `channel`, `tenant` | Who can open or resume the conversation |
| `memory` | `actor`, `tenant`, `agent`, `none` | Which Context Hub memory slice is remounted for the run |
| `credentials` | `agent`, `actor`, `none`, `custom` | Whose credentials downstream calls use |
If `tenancy` is `"single"`, do not set any scoping axis to `"tenant"`, there is no tenant to scope by. If a request is missing the actor or tenant 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).
### Custom downstream credentials
Use `scoping.credentials: "custom"` when your application can securely obtain a per-actor credential for a downstream target. Provide a `resolve` function; 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.
The following shape lets a user sign in through Supabase and open GitHub pull requests as themselves. After the user has separately authorized GitHub, your application stores the GitHub grant keyed by the Supabase user id. `getGitHubAccessToken` is application code: it looks up and refreshes that grant in your server-side credential store.
```ts identity.ts theme={null}
import { defineIdentity, providers } from "managed-deepagents";
import { getGitHubAccessToken } from "./github-credentials.js";
export const identity = defineIdentity({
ingress: {
http: {
mode: "validated_token",
providers: [providers.supabase({ projectRef: "your-project-ref" })],
},
},
tenancy: "single",
scoping: {
threads: "actor",
memory: "actor",
credentials: "custom",
},
credentials: {
async resolve({ identity, target }) {
if (target.name !== "github") {
throw new Error(`No credentials configured for ${target.name}.`);
}
const credential = await getGitHubAccessToken(identity.actor.id);
if (!credential) {
throw new Error("Connect GitHub before using GitHub tools.");
}
return {
headers: { Authorization: `Bearer ${credential.token}` },
expiresAt: credential.expiresAt.toISOString(),
};
},
},
});
```
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.
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.
## Provider setup guides
These guides cover the built-in providers for [validated token](#validated-token-browser-direct) ingress. Use one provider, or combine them as in the example in that section.
Anonymous visitors get a short-lived, actor-scoped session without signing in. Managed Deep Agents signs guest tokens with `MDA_GUEST_SIGNING_KEY` (HS256) and maps `sub` → actor.
| Option | Required | Description |
| ------------------------------ | -------- | ------------------------------------------------------- |
| `ttl` | No | Token lifetime (for example `"24h"`) |
| `actorPrefix` / `actor_prefix` | No | Prefix for generated actor 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 actor 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 actor id, threads, and memory scope for the token lifetime.
JWKS by default (asymmetric JWTs). Maps `sub` → actor. 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 `providers.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` → actor, `email` → email. `providers.github()` takes no options.
```python identity.py theme={null}
from managed_deepagents import define_identity, providers
identity = define_identity.preset(
"internal-tool",
{
"ingress": {
"http": {
"mode": "validated_token",
"providers": [providers.github()],
}
}
},
)
```
```ts identity.ts theme={null}
import { defineIdentity, providers } from "managed-deepagents";
export const identity = defineIdentity.preset("internal-tool", {
ingress: {
http: {
mode: "validated_token",
providers: [providers.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 [trusted backend](#trusted-backend-recommended-default) ingress: keep the GitHub token on your API, and proxy with `X-MDA-Ingress-Secret` + `X-MDA-Actor-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 trusted-backend proxies attach the reserved headers.
## Next steps
See how identity remounts per-actor or per-tenant memory.
Read `runtime.identity` from authored tools.
Run cron agents, including the `service` preset shape.
Expose constrained LangSmith capabilities to untrusted callers.
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).